AI-ready version:

Get a List of Certificates

Description

This API allows you to retrieve a list of certificates associated with a specific app_token and remote_user_id. The response includes detailed certificate information, such as the certificate ID, URLs, design options, impact data, and geolocation.

Endpoint

GET https://impact.dots.eco/api/v1/certificate/list/{app_token}/{remote_user_id}

For details about required headers and authentication, refer to Headers and Authorization.

Parameters

Name	Required	Type	Description
`app_token`	Yes	`string`	A unique application identifier (first part of the application UUID in Dots.eco).
`remote_user_id`	Yes	`string`	The user ID to whom the certificates are issued.

Example Requests

Minimal Request Example

curl --location --request GET 'https://impact.dots.eco/api/v1/certificate/list/APP_TOKEN/REMOTE_USER_ID' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Responses

Example Successful Response

A successful request returns an array of certificates belonging to the specified user and application.

[
  {
      "certificate_id": "134410-6-5",
      "certificate_url": "https://impact.dots.eco/certificate/c7cd3320-1f15-4127-a5e4-6935abcf5fc9",
      "certificate_image_url": "https://impact.dots.eco/certificate/img/c7cd3320-1f15-4127-a5e4-6935abcf5fc9.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": 185,
      "impact_type_name": "Wildlife land",
      "impact_status": null,
      "created_timestamp": 1663080111,
      "allocation_id": "8",
      "country": "Grenada",
      "geolocation": null,
      "certificate_header": "For saving 1 Sea-Turtle hatchlings with Dots.eco",
      "greeting": "Thank you Tom!"
  },
  {
      "certificate_id": "134411-6-5",
      "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": "silver",
      "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": "Ethiopia",
      "geolocation": [
          {
              "lat": 7.2015830000000003,
              "lng": 37.253971999999997
          }
      ],
      "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 of the certificate.
`certificate_url`	`string`	The URL where the certificate can be viewed.
`certificate_image_url`	`string`	The URL for the certificate's image.
`app_id`	`string`	The ID of the app associated with the certificate.
`app_name`	`string`	The name of the app associated with the certificate.
`remote_user_id`	`string`	The user ID of the certificate recipient.
`name_on_certificate`	`string`	The name displayed on the certificate.
`certificate_design`	`string`	The design of the certificate, if applicable.
`certificate_info`	`string`	Additional details about the certificate, or `null` if not provided.
`impact_qty`	`number`	The quantified impact associated with the certificate.
`impact_type_id`	`number`	A unique ID for the type of impact represented by the certificate.
`impact_type_name`	`string`	The name of the impact type (e.g., "Wildlife land").
`impact_status`	`string`	Status of the certificate impact (null if unspecified).
`created_timestamp`	`number`	The Unix timestamp indicating when the certificate was created.
`allocation_id`	`string`	The allocated resource associated with the certificate.
`country`	`string`	The country where the impact was allocated or occurred.
`geolocation`	`array`	A list of geolocations, with each entry including `lat` and `lng`.
`geolocation.lat`	`number`	The latitude of the impact's geolocation.
`geolocation.lng`	`number`	The longitude of the impact's geolocation.
`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

Returned when the app_token or remote_user_id is invalid or missing.

Error Message	Explanation
`"The app_token is invalid."`	The provided `app_token` is not valid or missing.

404 Not Found

Returned when the specified user does not exist for the given app_token.

Error Message	Explanation
`"The given user doesn't exist."`	No user found for the given `remote_user_id`.

HTTP Status Codes

Code	Description
200	The request was completed successfully.
422	Parameters were missing or contained invalid values.
404	The specified user was not found.

Notes

Ensure both app_token and remote_user_id are included in the request for proper functionality.
For header setup, refer to the Headers and Authorization guide.
The geolocation field may be null if no specific location is associated with the impact.