GET /api/listsDescription:
Retrieve a list of all certificate lists associated with the authenticated user.
Method: GET
Authentication:
Requires user authentication via token (e.g., Bearer Token).
Request Parameters:
page (optional):
The page number for pagination. Default is 1.
per_page (optional):
Number of results per page. Default is 15. Max is configurable depending on your application.
Request Headers:
<token>Response:
200 OKResponse Body:
{
"data": [
{
"id": 1,
"name": "Certificate List 1",
"custom_fields": ["course_name", "completion_date", "instructor_name"],
"created_at": "2023-10-01T12:00:00.000000Z",
"updated_at": "2023-10-02T12:00:00.000000Z"
},
{
"id": 2,
"name": "Certificate List 2",
"custom_fields": [],
"created_at": "2023-10-02T12:30:00.000000Z",
"updated_at": "2023-10-03T14:00:00.000000Z"
}
],
"links": {
"first": "http://example.com/api/lists?page=1",
"last": "http://example.com/api/lists?page=5",
"prev": null,
"next": "http://example.com/api/lists?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"per_page": 15,
"to": 15,
"total": 75
}
}
Response Fields:
data: A collection of certificate lists.
id: The unique identifier of the list.name: The name of the certificate list.custom_fields: An array of custom field names available for recipients in this list. These fields are defined in the certificate design associated with the list.created_at: The date and time when the certificate list was created.updated_at: The date and time when the certificate list was last updated.links: Pagination links.
first: URL to the first page of results.last: URL to the last page of results.prev: URL to the previous page of results, if applicable.next: URL to the next page of results, if applicable.meta: Pagination metadata.
current_page: The current page number.from: The starting index of the current page of results.last_page: The last page number.per_page: The number of items per page.to: The ending index of the current page of results.total: The total number of available certificate lists.Errors:
GET /api/recipientsDescription:
Retrieve a list of all recipients associated with certificate lists belonging to the authenticated user.
Method: GET
Authentication:
Requires user authentication via token (e.g., Bearer Token).
Request Parameters:
page (optional):
The page number for pagination. Default is 1.
per_page (optional):
Number of results per page. Default is 15. Max is configurable depending on your application.
Request Headers:
<token>Response:
200 OKResponse Body:
{
"data": [
{
"id": 1,
"list_id": 1,
"email": "recipient@example.com",
"name": "John Doe",
"status": "issued",
"uuid": "abcd-1234-efgh-5678",
"issued_date": "2023-10-01T12:00:00+00:00",
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-02T12:00:00+00:00"
},
{
"id": 2,
"list_id": 2,
"email": "another@example.com",
"name": "Jane Smith",
"status": "draft",
"uuid": "ijkl-5678-mnop-1234",
"issued_date": "2023-09-28T10:00:00+00:00",
"created_at": "2023-09-28T10:00:00+00:00",
"updated_at": "2023-09-29T10:00:00+00:00"
}
],
"links": {
"first": "http://example.com/api/recipients?page=1",
"last": "http://example.com/api/recipients?page=5",
"prev": null,
"next": "http://example.com/api/recipients?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 5,
"per_page": 15,
"to": 15,
"total": 75
}
}
Response Fields:
data: A collection of recipient records.
id: The unique identifier of the recipient.list_id: The ID of the certificate list the recipient is associated with.email: The email address of the recipient.name: The name of the recipient.status: The current status of the recipient (e.g., draft, issued).uuid: A unique identifier for the recipient (e.g., a GUID).issued_date: The date when the certificate was issued to the recipient. If not set, null will be returned.created_at: The timestamp when the recipient was created.updated_at: The timestamp when the recipient was last updated.links: Pagination links.
first: URL to the first page of results.last: URL to the last page of results.prev: URL to the previous page of results, if applicable.next: URL to the next page of results, if applicable.meta: Pagination metadata.
current_page: The current page number.from: The starting index of the current page of results.last_page: The last page number.per_page: The number of items per page.to: The ending index of the current page of results.total: The total number of available recipients.Errors:
POST /api/recipientsDescription: Add a new recipient to a certificate list associated with the authenticated user. If a recipient with the same email already exists in the list, it will be updated with new custom field data or skipped if the data is identical.
Method: POST
Authentication: Requires user authentication via token (e.g., Bearer Token).
Request Parameters (Body):
{
"list_id": 1,
"email": "recipient@example.com",
"name": "John Doe",
"custom_fields": {
"course_name": "Introduction to AI",
"completion_date": "2023-10-01"
}
}
list_id (required, integer):
The ID of the certificate list the recipient will be added to. This list must exist and belong to the authenticated user.
email (required, string):
The email address of the recipient. It must be a valid email format.
name (required, string):
The full name of the recipient. Maximum length is 255 characters.
custom_fields (optional, object):
Key-value pairs of custom fields for the certificate. Each key must match a custom field defined in the certificate design. Keys must contain only alphanumeric characters, hyphens, and underscores. Values must be strings with a maximum length of 500 characters.
Request Headers:
<token>
A valid API token must be included in the request header to authenticate the user.Response:
201 Created (when a new recipient is created)200 OK (when an existing recipient is updated or skipped)Response Body (Success):
{
"status": true,
"message": "Recipient created successfully.",
"data": {
"id": 1,
"list_id": 1,
"email": "recipient@example.com",
"name": "John Doe",
"status": "draft",
"uuid": "abcd-1234-efgh-5678",
"issued_date": null,
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-01T12:00:00+00:00",
"action": "created"
}
}
status: Indicates whether the operation was successful (true).message: A message describing the result of the operation. Possible values:
"Recipient created successfully." - New recipient was created"Recipient updated with new custom field data." - Existing recipient was updated"Recipient already exists with identical data." - No changes were madedata: The recipient object with the following fields:
id: The unique identifier of the recipient.list_id: The ID of the certificate list the recipient is associated with.email: The email address of the recipient.name: The name of the recipient.status: The status of the recipient (e.g., draft, issued).uuid: A unique identifier for the recipient (UUID).issued_date: The date when the certificate was issued to the recipient. If not issued yet, null.created_at: The timestamp when the recipient was created.updated_at: The timestamp when the recipient was last updated.action: The action taken. Possible values: created, updated, skipped.Response (Errors):
404 Not Found:
If the specified list_id does not exist.
Response Example:
{
"status": false,
"message": "The list you are trying to access does not exist."
}
403 Forbidden: If the authenticated user does not have permission to access the specified list.
Response Example:
{
"status": false,
"message": "You are not authorized to perform this action."
}
422 Unprocessable Entity: If the input validation fails (e.g., missing required fields, invalid email format, or invalid custom fields).
Response Example (Validation Error):
{
"status": false,
"message": "Validation failed.",
"errors": {
"email": ["The email must be a valid email address."]
}
}
Response Example (Invalid Custom Field):
{
"status": false,
"message": "Custom field 'invalid_field' is not available for this certificate design. Available fields: course_name, completion_date"
}
500 Internal Server Error: If there is an unexpected server error during recipient creation.
Response Example:
{
"status": false,
"message": "An error occurred while creating the recipient.",
"error": "Error details here"
}
GET /api/recipients/searchDescription: Search for recipients by email address within certificate lists belonging to the authenticated user. Optionally filter by recipient status.
Method: GET
Authentication: Requires user authentication via token (e.g., Bearer Token).
Request Parameters (Query):
email (required, string):
The email address to search for. Partial matches are supported.
status (optional, string):
Filter results by recipient status. Allowed values: draft, issued.
page (optional, integer):
The page number for pagination. Default is 1.
Request Headers:
<token>
A valid API token must be included in the request header to authenticate the user.Example Request:
GET /api/recipients/search?email=john@example.com&status=issued
Response:
200 OKResponse Body:
{
"data": [
{
"id": 1,
"list_id": 1,
"email": "john@example.com",
"name": "John Doe",
"status": "issued",
"uuid": "abcd-1234-efgh-5678",
"issued_date": "2023-10-01T12:00:00+00:00",
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-02T12:00:00+00:00"
}
],
"links": {
"first": "http://example.com/api/recipients/search?email=john@example.com&page=1",
"last": "http://example.com/api/recipients/search?email=john@example.com&page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 15,
"to": 1,
"total": 1
}
}
Response Fields:
data: A collection of matching recipient records.links: Pagination links.meta: Pagination metadata.Response (Errors):
422 Unprocessable Entity: If the email parameter is missing or invalid.
Response Example:
{
"message": "The email field is required.",
"errors": {
"email": ["The email field is required."]
}
}
401 Unauthorized: If the user is not authenticated.
DELETE /api/recipients/{id}Description:
Delete a recipient from a certificate list associated with the authenticated user.
Method: DELETE
Authentication:
Requires user authentication via token (e.g., Bearer Token).
URL Parameters:
id (required, integer):Request Headers:
<token>Response:
200 OK (on success)Response Body (Success):
{
"status": true,
"message": "Recipient deleted successfully."
}
Response Fields:
status: Indicates whether the operation was successful (true or false).message: A message describing the result of the operation.Response (Errors):
404 Not Found:
If the recipient does not exist or is not associated with the authenticated user.
Response Example:
{
"status": false,
"message": "Recipient not found or not associated with your account."
}
500 Internal Server Error:
If an unexpected error occurs during the deletion process.
Response Example:
{
"status": false,
"message": "An error occurred while deleting the recipient.",
"error": "Error details here"
}
POST /api/recipients/{id}/issueDescription:
Issue a certificate to a specific recipient in the authenticated user's certificate list.
Method: POST
Authentication:
Requires user authentication via token (e.g., Bearer Token).
URL Parameters:
id (required, integer):Request Headers:
<token>Response:
200 OK (on success)Response Body (Success):
{
"status": true,
"recipient": {
"id": 1,
"list_id": 1,
"email": "recipient@example.com",
"name": "John Doe",
"status": "issued",
"uuid": "abcd-1234-efgh-5678",
"issued_date": "2023-10-01T12:00:00+00:00",
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-01T12:00:00+00:00"
}
}
status: Indicates whether the operation was successful (true).recipient: Contains the updated recipient details including the issued_date and other recipient-related information.Response (Errors):
404 Not Found:
If the recipient does not exist or is not associated with the authenticated user.
Response Example:
{
"status": false,
"message": "Recipient not found or you do not have access to this recipient."
}
500 Internal Server Error:
If an unexpected error occurs while issuing the certificate.
Response Example:
{
"status": false,
"message": "An error occurred while issuing the certificate.",
"error": "Error details here"
}
POST /api/recipients/issueDescription:
Issue certificates to a group of recipients belonging to the authenticated user's certificate lists.
Method: POST
Authentication:
Requires user authentication via token (e.g., Bearer Token).
Request Body:
{
"recipient_ids": [1, 2, 3]
}
recipient_ids (required, array of integers):Request Headers:
<token>Response:
200 OK (on success)Response Body (Success):
{
"status": true,
"recipients": [
{
"id": 1,
"list_id": 1,
"email": "recipient1@example.com",
"name": "John Doe",
"status": "issued",
"uuid": "abcd-1234-efgh-5678",
"issued_date": "2023-10-01T12:00:00+00:00",
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-01T12:00:00+00:00"
},
{
"id": 2,
"list_id": 1,
"email": "recipient2@example.com",
"name": "Jane Doe",
"status": "issued",
"uuid": "ijkl-2345-mnop-6789",
"issued_date": "2023-10-01T12:00:00+00:00",
"created_at": "2023-10-01T12:00:00+00:00",
"updated_at": "2023-10-01T12:00:00+00:00"
}
]
}
status: Indicates whether the operation was successful (true).recipients: A collection of recipient objects, each containing the updated details such as issued_date and other recipient-related information.Response (Errors):
422 Unprocessable Entity (Validation Error):
If the recipient_ids array is invalid or the IDs do not exist in the database.
Response Example:
{
"status": false,
"message": "Validation failed.",
"errors": {
"recipient_ids": [
"The selected recipient_ids is invalid."
]
}
}
404 Not Found:
If no valid recipients are found or the authenticated user does not have access to them.
Response Example:
{
"status": false,
"message": "No valid recipients found or you do not have access to them."
}
500 Internal Server Error:
If an unexpected error occurs while issuing the certificates.
Response Example:
{
"status": false,
"message": "An error occurred while issuing certificates.",
"error": "Error details here"
}