AI-ready version:

Create Certificate

Description

This API allows for creating a new certificate for a specific user and allocation. It provides flexibility to include user-specific details, impact data, and optional metadata.

Endpoint

POST https://impact.dots.eco/api/v1/certificate/add

Refer to Headers and Authorization for information about the required headers and authentication.

Parameters

Name	Required	Type	Description
`app_token`	Yes	`string`	The app identifier, found in the app dashboard.
`external_unique_id`	No	`string (max_length=255)`	A unique identifier for the certificate to prevent duplicate processing and permit error recovery.
`impact_qty`	Yes	`integer (max_value=10^11)`	The quantity of the user’s impact.
`allocation_id`	Yes	`integer (max_value=10^10)`	The allocation ID linked to the certificate.
`remote_user_id`	Yes	`string (max_length=191)`	The ID of the user associated with the certificate. If the user doesn’t exist, a new user will be created.
`name_on_certificate`	No	`string (max_length=255)`	The name to be printed on the certificate.
`remote_user_email`	No	`string (max_length=254)`	The email of the user. When omitted, a default email like `{remote_user_id}@dots.eco` will be generated.
`certificate_design`	No	`string (max_length=255)`	The template design for the certificate. Coordinate with the Dots.eco team for available templates.
`send_certificate_by_email`	No	`string`	Set to `yes` to email the certificate to the user.
`certificate_info`	No	`string (max_length=255)`	Metadata related to the certificate, such as a transaction or order ID.
`langcode`	No	`string (max_length=12)`	The language code for the certificate. A list of supported languages can be found here. If an unsupported language code is provided, the default language will be used instead.
`currency`	No	`string`	The currency type for the certificate. A list of supported currencies can be found here.

Example Requests

Minimal Request Example

curl --location --request POST 'https://impact.dots.eco/api/v1/certificate/add' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN' \
--data-raw '{
    "app_token": "YOUR_APPLICATION_TOKEN",
    "external_unique_id": "2132-1232-22",
    "impact_qty": 10,
    "allocation_id": 14,
    "remote_user_id": "john_doe_123"
}'

Full Example Request

{
    "app_token": "101-5653d113",
    "external_unique_id": "2132-1232-22",
    "impact_qty": 10,
    "allocation_id": 14,
    "remote_user_id": "john_doe_123",
    "remote_user_email": "john.doe@example.com",
    "name_on_certificate": "John Doe",
    "certificate_design": "basic-template",
    "send_certificate_by_email": "yes",
    "certificate_info": "order-12345",
    "langcode": "en",
    "currency": "USD"
}

Responses

Example Successful Response

A successful certificate creation request returns a JSON object containing all details of the certificate.

{
    "certificate_id": "134411-6-5",
    "external_unique_id": "1232-122-122",
    "certificate_url": "https://impact.dots.eco/certificate/1ca15b15-dec1-494b-884f-a9fefa953a67",
    "certificate_image_url": "https://impact.dots.eco/certificate/img/1ca15b15-dec1-494b-884f-a9fefa953a67.jpg",
    "app_id": "6",
    "app_name": "Dots.eco",
    "remote_user_id": "testuser",
    "name_on_certificate": "John Doe",
    "certificate_design": null,
    "certificate_info": null,
    "impact_qty": "1",
    "impact_type_id": "196",
    "impact_type_name": "Save a Sea Turtle",
    "impact_status": null,
    "created_timestamp": "1663080297",
    "allocation_id": "14",
    "country": "Indonesia",
    "geolocation": [
        {
            "lat": -8.1420890000000004,
            "lng": 114.65480599999999
        }
    ],
    "certificate_header": "For saving 1 Sea-Turtle hatchlings with Dots.eco",
    "greeting": "Thank you Tom!"
}

Response Fields

Field	Type	Description
`certificate_id`	`string`	The unique ID assigned to the certificate.
`external_unique_id`	`string`	The user-provided unique identifier for the certificate (if specified).
`certificate_url`	`string`	URL to view or download the certificate.
`certificate_image_url`	`string`	The URL for the image of the certificate.
`app_id`	`string`	The unique identifier of the application linked to the certificate.
`app_name`	`string`	The name of the application.
`remote_user_id`	`string`	The user ID receiving the certificate.
`name_on_certificate`	`string`	The name displayed on the certificate.
`certificate_design`	`string`	Details of the template design used for the certificate.
`certificate_info`	`string`	Additional metadata relating to the certificate (e.g., transaction ID).
`impact_qty`	`string`	The quantity of the user’s impact linked to this certificate.
`impact_type_id`	`string`	A unique ID representing the type of impact.
`impact_type_name`	`string`	Description of the impact type (e.g., "Save a Sea Turtle").
`impact_status`	`string`	Status information for the impact linked to the certificate.
`created_timestamp`	`string`	A Unix timestamp indicating the certificate’s creation time.
`allocation_id`	`string`	The ID of the allocation connected to the certificate.
`country`	`string`	The country linked to the certificate’s impact.
`geolocation`	`array`	An array containing geolocation data (latitude and longitude).
`geolocation.lat`	`number`	Latitude of the geolocation related to the certificate’s impact.
`geolocation.lng`	`number`	Longitude of the geolocation related to the certificate’s impact.
`certificate_header`	`string`	The text displayed at the top of the certificate. It summarizes the environmental action completed by the user.
`greeting`	`string`	A personalized thank-you message displayed on the certificate or in the email. The user’s name is dynamically inserted.

Errors

422 Unprocessable Entity

Occurs when the request is invalid or missing required values.

Error Message	Explanation
`"The app_token is invalid."`	The provided `app_token` is invalid or missing.
`"You must provide a valid 'impact_qty' value to process."`	The `impact_qty` is invalid, missing, or exceeds the maximum allowed value.
`"You must provide a valid 'impact_type_id' or 'allocation_id' value to process."`	The `allocation_id` is not provided or invalid.
`"You must provide a valid 'remote_user_id' value to process."`	The provided `remote_user_id` is invalid or missing.
`"You must provide a valid email address for 'remote_user_email' value to process."`	The `remote_user_email` is invalid or improperly formatted.
`"The maximum length of [field] is [max_length] characters."`	A field exceeds its maximum length (e.g., `external_unique_id`, `email`).
`"A certificate with this external_unique_id already exists in the system."`	A duplicate `external_unique_id` was detected.
`"Provided app is not of type Certificate."`	The linked application doesn’t support certificate generation.

429 Too Many Requests

Occurs when the application exceeds its rate limits or allocated balance.

Error Message	Explanation
`"This application is out of balance. Check the documentation or contact support."`	The app has consumed all its allocation.

Notes

Ensure all mandatory parameters (app_token, impact_qty, allocation_id, remote_user_id) are included in the request.
This request require Write-only token.
Additional configuration instructions can be found in the Headers and Authorization and Supported Languages sections.