The Submissions API lets you access the data your Compositor collects — on demand and in JSON format — without setting up webhooks or third-party integrations.
Key Concepts
Webhooks push the submissions to your URL or application as soon as they’re submitted. With the API, however, you send a GET request each time you want to retrieve the submissions data.
The response includes all the submissions your Compositor units have received so far, in JSON format. You can also add query parameters to your requests so that responses include only certain submissions, for example made by a certain name or email. This page lists and describes all of the available query parameters.
The Submissions API is designed so that you can create your own web app to programmatically retrieve responses.
Version
The current version of the API is V1.
Requirements
All you need to do is sign up for a plan and generate an API key to access the API.
Authentication
Authentication with the Compositor API is achieved by sending your Api-Key along in the header of every request:
api: “YOUR_API_KEY”
You can find and manage your Api Keys in your account settings. Be sure to keep them secret! You should not share your API key anywhere where other people can see them.
API requests without authentication will fail. All of your API requests should be made over HTTPS.
Request and response format
Submissions and Webhooks use the HTTP protocols and GET for requests. They return responses in JSON data format.
Rate Limiting
The API uses rate limiting to help keep it stable. Users who send too many requests in quick succession may see error responses that show up as HTTP status code 429 with RateLimit error header field. You can retry requests when your quota resets.
The API rate limit is 80 requests per minute, which is more than enough for most cases.
Endpoint URL
The base URL for Submissions API is https://app.compositor.digital/api/v1/submissions/
Retrieve Submissions
| Request Method: | GET |
| Endpoint URL: | https://app.compositor.digital/api/v1/ submissions/ |
| Response: | 200 |
It will return a list of all the submissions across your canvas units and you can filter the data using query string parameters, for example
/?name=john&instance=new
Optional URL parameters
| Parameter | Description |
|---|---|
name | Show submissions from the specified name |
email | Show submissions from the specified email address |
title | Show submissions with certain title |
domain | Domain name to filter by |
instance | Show submissions for certain canvas instance |
approved | Show only approved submissions by /?approved=true. Default is FALSE |
limit | The requested number of objects per page. |
Retrieves all submissions created by John
The submissions returned are sorted by creation date, with the most recent ones appearing first.
Every request can retrieve these data fields: id, name, email, composition title, image url, width, height, thumbnail url, date, domain and instance name.
JSON response data explanation
The REST API lets you retrieve the submissions to your Compositors on demand and serialized in JSON format. Let’s take a look at each object in the payload.
The JSON structure has two root objects:
| Key | Description |
|---|---|
data | An array of objects returned for the specified page number. |
pagination | Pagination data, such as page numbers, counts, limits. |
At the top of each request payload, you’ll see status, message, data, which is an array of submission objects, and pagination.
{
"status": "success",
"message": null,
"data": [
// Array of objects
],
"pagination":{}
}statusis the status of the payload.messageis the message in the payload.datais an array of objects that make up the submissions to your instances. Each submission is one item.pagination– Pagination data, like page numbers and total objects count.
Pagination
| Key | Description |
current_page | Current page number returned. |
next_page | Next page number. Will be null if none. |
previous_page | Previous page number. |
count | The number of objects on the current page. |
limit | The requested number of objects per page. |
total_pages | The total number of pages. |
total_count | The total number of objects returned across all pages. |
Data object
Each submission is listed as a separate object in the Data array. Each item also includes information about the submission and submitter like the submission time, the user agent string (which tells you which device and browser the respondent used).
First, here’s what a complete JSON response for our example Compositor unit looks like:
GET https://app.compositor.digital/api/v1/submissions?name=john
{
"status": "Success",
"message": null,
"data": [
{
"id": 334,
"approved": "false",
"name": "john doe",
"email": "john@mkcsite.com",
"composition_title": "my great comp",
"domain": "mkcsite.com",
"instance": "My first Instance",
"width": 200,
"height": 150,
"image_url": "https://storage.googleapis.com/canv/1679016679-pPfGvNBwuJ.jpeg",
"thumbnail_url": "https://storage.googleapis.com/canv/thumbnails/1679016679-mOyOUg4pSV-thumb.jpeg",
"date": "2023-03-17 01:31:20"
}
],
"pagination": {
"previous_page": null,
"next_page": null,
"current_page": 0,
"count": 1,
"limit": 25,
"total_count": 1,
"total_pages": 1
}
}Our example has one submission.
Example setup on Reqbin:
| Endpoint URL | https://app.compositor.digital/api/v1/submissions |
| Method | GET |
| Header | api: klyNbBuggJS9i80ksDaE8YXfzxIcux |
Errors
If your API request causes an error, the response will contain an error object that includes information to help you resolve the problem.
Missing authorization or passing an invalid API key will return a 422 Unprocessable Entity JSON response:
status: "Error"
message: "provided API key was not found."Webhooks
Optionally send the data to a webhooks URL whenever a submission is received. Data items sent by the webhook would be the same as with the API.
With our Webhooks API, you can send every submission straight to any URL or compatible web application as soon as it is submitted.
Key concepts
Webhooks are notifications that are triggered automatically when a specific event occurs and sent through the web. With our Webhooks enabled API, the event is a new image submission. When a new submission comes in, a notification that contains the submission data is immediately sent to your chosen destination: the URL or web application you set. Your webhook should send a 2XX HTTP response status code back to let Compositor know that you received the webhook data.
Retrying failed webhook deliveries
When the app to which we’re sending the webhook fails to send a response with a 2xx status code the package will consider the call as failed. The call will also be considered failed if the remote app doesn’t respond within 3 seconds.
If a webhook request fails for any reason, it will retry the request to your endpoint 5 times, for 1 day.
To not hammer the remote app we’ll wait some time between each attempt. By default, we wait 10 seconds between the first and second attempt, 100 seconds between the third and the fourth and so on.
Endpoint
You can add, edit, or remove endpoints from the Webhooks tab in your instance’s dashboard.
And endpoint is simply a URL on your application that Compositor will send data to when an event occurs.
Webhook data is sent as JSON in the POST request body to your configured endpoints. The payload has an object that represents the submission event. The object’s JSON structure will be identical to the structure returned by the REST API endpoint.