NAV Navbar
shell

Introduction

Welcome to Collect Developer documentation.

The Collect REST API is a collection of HTTPS endpoints to enable any application that supports HTTPS requests to send and receive data from a Collect account.

Authentication

To authorize, use this code:

curl "api_endpoint_here"
  --user ":YourApiKey"

Make sure to replace YourApiKey with your API key.

Collect uses API keys to allow access to the API. You can retrieve your Collect API key at the bottom of your profile page.

You need to add the Authorization header using the Basic authentication type. login:password where the login is always empty and the password is the API key.

Teams

Get Team Information

curl "https://api.usecollect.com/api/v1/team"
  --user ":YourApiKey"

The above command returns JSON structured like this:

{
    "_id": "DbdjhXBn7diDF8jdc",
    "tz": "Europe/Paris",
    "name": "Collect",
    "conso": {
        "request": 135,
        "sms": 0,
        "users": 5,
        "storage": 23768,
        "templates": 2
    },
    "plan": {
        "name": "Free Plan",
        "end": "2019-07-22T13:25:15.000Z"
    }
}

This endpoint retrieves information of your team.

HTTP Request

GET https://api.usecollect.com/api/v1/team

Query Parameters

No parameters

Campaigns

List all campaigns

curl "https://api.usecollect.com/api/v1/campaigns?offset=0&limit=10"
  --user ":YourApiKey"

The above command returns JSON structured like this:

[
    {
        "_id": "mYCsdgB4DQoENBaX6",
        "name": "Scholarship application",
        "createdAt": "2018-11-22T13:28:08.215Z",
        "count": {
            "request": 72,
            "open": 4,
            "done": 61,
            "due": 5,
            "waiting": 2,
            "error": 0,
            "message": 0
        }
    },
    {
        "_id": "wFndw23xmx5RdWrFX",
        "name": "Company KYC",
        "createdAt": "2019-01-31T09:49:25.621Z",
        "count": {
            "request": 22,
            "open": 4,
            "done": 18,
            "due": 0,
            "waiting": 0,
            "error": 0,
            "message": 0
        }
    }
]

This endpoint retrieves all the campaigns.

HTTP Request

GET https://api.usecollect.com/api/v1/campaigns

Query Parameters

Parameter Description
offset Optionally specify the ranking number of the first item on the page. Used for pagination.
limit Optionally specify how many results to return. Default is 50 campaigns, maximum is 100 campaigns.

Requests

List all the requests of a campaign

curl -X POST "https://api.usecollect.com/api/v1/requests?campaignId=mYCsdgB4DQoENBaX6&offset=0&limit=2"
  --user ":YourApiKey"
  --data

The above command returns JSON structured like this:

[
    {
        "_id": "NxAHPWu9hRzcyD24m",
        "campaignId": "mYCsdgB4DQoENBaX6",
        "createdAt": "2019-05-22T13:40:26.671Z",
        "status": "due",
        "dueDate": "2019-06-12T22:59:00.000Z",
        "privacy": "team",
        "contact": {
            "_id": "uBJadNFcjrC6emRom",
            "email": "elon@example.com",
            "firstName": "Elon",
            "lastName": "Musk",
            "nbRequest": 11,
            "tag": [],
            "custom": [
                {
                    "_id": "yw6XDyeFvbqr86yA6",
                    "name": "Favorite color",
                    "variable": "color",
                    "value": "Blue"
                },
                {
                    "_id": "CqdFwGX3yitk9zf8z",
                    "name": "Country",
                    "variable": "country",
                    "value": "US"
                }
            ],
            "createdAt": "2018-11-22T13:40:26.591Z",
            "lastActivity": "2019-06-17T17:14:52.498Z"
        },
        "branding": {
            "useBranding": true,
            "brandingId": "jSEj7vHk3wLG3gRF7"
        }
    }
]

This endpoint retrieves all the requests of a campaign.

HTTP Request

GET https://api.usecollect.com/v1/requests?campaignId=mYCsdgB4DQoENBaX6&offset=10&limit=20

Query Parameters

Parameter Description
campaignId (Mandatory) Specify the ID of the campaign to retrieve.
offset Optionally specify the ranking number of the first item on the page. Used for pagination.
limit Optionally specify how many results to return. Default is 50 campaigns, maximum is 100 campaigns.
filter Optionally filter requests by status. If not specify, will return all the requests except request cancelled, archived and the drafts.

Below you will find the data dictionary for the status attribute.

Status Description
pending The request has been sent and is not completed.
completed The request has been sent, all the documents have been uploaded. If validation is opted-in, the documents have been validated too.
due The request has been sent, is not completed and is due.
waiting The request has been sent, all the documents have been uploaded but they have not been validated by the user.
archived The request has been archived.
cancelled The request has been cancelled.
error An error happened when we sent the request.

Send a new request

curl "https://api.usecollect.com/v1/requests"
  --user ":YourApiKey"
  --data '{"campaignId": "xvr69EYLKXvTkfYuk", "contacts": ["WmTjsFknzHdmfs3Ra", {"email": "elon@example.com", "firstName": "Elon", "lastName": "Musk"}]' \

The above command returns JSON structured like this:

{
    "requests": [
        {
            "_id": "nw42MmBsJoccgutST",
            "campaignId": "xvr69EYLKXvTkfYuk",
            "createdAt": "2019-07-04T07:20:06.085Z",
            "status": "pending",
            "dueDate": "2019-07-11T21:59:00.000Z",
            "privacy": "private",
            "contact": {
                "_id": "WmTjsFknzHdmfs3Ra",
                "email": "johndoe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "nbRequest": 5,
                "createdAt": "2019-07-03T13:51:27.666Z",
                "lastActivity": "2019-07-04T07:20:06.080Z"
            },
            "branding": {
                "useBranding": false
            }
        },
        {
            "_id": "jdDzbxP8MnfBdrRuM",
            "campaignId": "xvr69EYLKXvTkfYuk",
            "createdAt": "2019-07-04T07:20:06.116Z",
            "status": "pending",
            "dueDate": "2019-07-11T21:59:00.000Z",
            "privacy": "private",
            "contact": {
                "_id": "ngxhLDiDGEBS2jjKh",
                "email": "elon@example.com",
                "firstName": "Elon",
                "lastName": "Musk",
                "nbRequest": 1,
                "createdAt": "2019-07-04T07:20:06.059Z",
                "lastActivity": "2019-07-04T07:20:06.113Z"
            },
            "branding": {
                "useBranding": false
            }
        }
    ],
    "contacts": [
        "WmTjsFknzHdmfs3Ra",
        {
            "_id": "ngxhLDiDGEBS2jjKh",
            "email": "elon@example.com",
            "firstName": "Elon",
            "lastName": "Musk",
            "createdAt": "2019-07-04T07:20:06.059Z"
        }
    ],
    "errors": []
}

This endpoint allows you to send new requests to new contacts or existing contacts.

HTTP Request

POST http://api.usecollect.com/v1/requests/

Body Parameters

Parameter Description
campaignId (Mandatory) The ID of the campaign you want to send a request.
contacts (Mandatory) An array of the contacts you want to send the request to. You can send requests up to 50 contacts per API call (considering your account's limitation). Each contact can be a string representing the ID of an existing contact or a contact object in JSON format (click here for more details).

Get a specific request

curl "https://api.usecollect.com/v1/requests/:requestId?expires=40"
  --user ":YourApiKey"

The above command returns JSON structured like this:

{
    "_id": "NxAHPWu9hRzcyD24m",
    "campaignId": "mYCsdgB4DQoENBaX6",
    "createdAt": "2019-05-22T13:40:26.671Z",
    "status": "due",
    "dueDate": "2019-06-12T22:59:00.000Z",
    "privacy": "team",
    "contact": {
        "_id": "uBJadNFcjrC6emRom",
        "email": "elon@example.com",
        "firstName": "Elon",
        "lastName": "Musk",
        "nbRequest": 11,
        "tag": [],
        "custom": [
            {
                "_id": "yw6XDyeFvbqr86yA6",
                "name": "Favorite color",
                "variable": "color",
                "value": "Blue"
            },
            {
                "_id": "CqdFwGX3yitk9zf8z",
                "name": "Country",
                "variable": "country",
                "value": "US"
            }
        ],
        "createdAt": "2018-11-22T13:40:26.591Z",
        "lastActivity": "2019-06-17T17:14:52.498Z"
    },
    "branding": {
        "useBranding": true,
        "brandingId": "jSEj7vHk3wLG3gRF7"
    },
    "documents": [
        {
            "name": "ID",
            "status": "waiting",
            "extensions": [
                "pdf"
            ],
            "multipleupload": true,
            "uploads": [
                {
                    "createdAt": "2019-06-13T14:01:31.777Z",
                    "name": "Elon's ID.pdf",
                    "url": "https://collectuseast.s3.amazonaws.com/elon_id.pdf?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=bglKxNBqqcDKkAeuzmxoBS2IOQQ%3D",
                    "size": 2414511
                }
            ]
        },
        {
            "name": "Bank statement",
            "status": "waiting",
            "extensions": [
                "zip",
                "rar",
                "gzip",
                "gz"
            ],
            "multipleupload": true,
            "sample": {
                "name": "bank_statement.pdf",
                "url": "https://collectsamples.s3.amazonaws.com/bank_statement.pdf"
            },
            "uploads": [
                {
                    "createdAt": "2019-06-13T15:59:36.975Z",
                    "name": "bank_statement.zip",
                    "url": "https://collectuseast.s3.amazonaws.com/bank_statement.zip?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=FRsF%2FP7QFIUyQ2PIRHn0NidCivI%3D",
                    "size": 42573459
                }
            ]
        }
    ]
}

This endpoint retrieves all the details of a specific request including the documents that have been uploaded.

HTTP Request

GET http://api.usecollect.com/v1/requests/:requestId?expires=40

URL Parameters

Parameter Description
ID The ID of the request to retrieve

Query Parameters

Parameter Description
expires Optionally specify the period of validity of the url to access the uploaded documents. Should be an integer, default is 900 (15 minutes) and maximum is 3600 (1 hour).

Notes

For security purpose, the urls of the documents uploaded expires after few minutes. Default is 15 minutes but you can specify a longer timing in parameters.

Contacts

List all contacts

curl "https://api.usecollect.com/v1/contacts?offset=0&limit=10&sort=lnAsc&search=doe"
  --user ":YourApiKey"

The above command returns JSON structured like this:

[
    {
        "_id": "uBJadNFcjrC6emRom",
        "email": "johndoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "nbRequest": 11,
        "tag": [ "Speaker" ],
        "custom": [
            {
                "_id": "yw6XDyeFvbqr86yA6",
                "name": "Favorite color",
                "variable": "color",
                "value": "Blue"
            },
            {
                "_id": "CqdFwGX3yitk9zf8z",
                "name": "Country",
                "variable": "country",
                "value": "US"
            }
        ]
    },
]

This endpoint retrieves all the contacts shared by the team.

HTTP Request

GET https://api.usecollect.com/v1/contacts

Query Parameters

Parameter Description
offset Optionally specify the ranking number of the first item on the page. Used for pagination.
limit Optionally specify how many results to return. Default is 50 campaigns, maximum is 100 campaigns.
sort Optionally specify how to sort the results to return. Default is by firstName and lastName ascending. You can order by firstName (fnAsc and fnDesc), lastName (lnAsc, lnDesc), email (emAsc, emDesc) or by tag (tagAsc, tagDesc)
search Optionally specify a string to look up. Search works on firstName, lastName, email and tags fields and is not case sensitive.

Get a specific contact

curl "https://api.usecollect.com/v1/contacts/:contactId"
  --user ":YourApiKey"

The above command returns JSON structured like this:

{
    "_id": "uBJadNFcjrC6emRom",
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "nbRequest": 11,
    "tag": [ "Speaker" ],
    "custom": [
        {
            "_id": "yw6XDyeFvbqr86yA6",
            "name": "Favorite color",
            "variable": "color",
            "value": "Blue"
        },
        {
            "_id": "CqdFwGX3yitk9zf8z",
            "name": "Country",
            "variable": "country",
            "value": "US"
        }
    ],
    "createdAt": "2019-02-22T13:40:26.591Z",
    "lastActivity": "2019-06-19T17:14:52.498Z",
    "requests": [
        {
            "_id": "NxAHPWu9hRzcyD24m",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-02-22T13:40:26.671Z",
            "status": "completed",
            "privacy": "team",
            "branding": {
                "useBranding": false
            }
        },
        {
            "_id": "jP6sXJ72R8xjxceaP",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-04-19T13:58:07.310Z",
            "status": "completed",
            "privacy": "team",
            "branding": {
                "useBranding": false
            },
            "note": {
                "date": "2019-05-04T14:25:17.254Z",
                "note": "Asked him to send back another document"
            }
        },
        {
            "_id": "FmZNnerEFRF3dLYPK",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-06-18T16:19:46.420Z",
            "status": "pending",
            "privacy": "team",
            "branding": {
                "useBranding": true,
                "brandingId": "jSEj7vHk3wLG3gRF7"
            }
        }
    ]
}

This endpoint retrieves a specific request.

HTTP Request

GET https://api.usecollect.com/v1/contacts/:contactId

URL Parameters

Parameter Description
contactId (Mandatory) Specify the ID of the contact to retrieve.

Notes

The list of requests is limited to 50 results.

Add a contact

curl -X POST "https://api.usecollect.com/v1/contacts"
  --data '{"email": "john@example.com", firstName" : "John", "lastName" : "Doe" }'
  --user ":YourApiKey"
  -H "application/json"

The above command returns JSON structured like this:

{
    "_id": "uBJadNFcjrC6emRom",
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "nbRequest": 0,
    "tag": [ "Speaker" ],
    "custom": [
        {
            "_id": "yw6XDyeFvbqr86yA6",
            "name": "Favorite color",
            "variable": "color",
            "value": "Blue"
        },
        {
            "_id": "CqdFwGX3yitk9zf8z",
            "name": "Country",
            "variable": "country",
            "value": "US"
        }
    ],
    "createdAt": "2019-02-22T13:40:26.591Z",
    "requests": []
}

This endpoint add a new contact. It returns the contact object.

HTTP Request

POST https://api.usecollect.com/v1/contacts

Body Parameters

Body is mandatory and must be a JSON object with the information you want to add.

Parameter Description
firstName (Optional) Specify the firstName of the contact.
lastName (Optional) Specify the lastName of the contact.
email Specify the email of the contact.
tag (Optional) You can specify the tags you want to add to the contact.
customFields (Optional) You can add the values of the custom fields by posting an array of object. To add the value of a custom field, you need to specify the _id of the custom field or the variable. If you want to create a custom field that doesn't exist, you need to specify the variable (must be lowercase and without special caracter), the name and the value.

Modify a contact

curl -X POST "https://api.usecollect.com/v1/contacts/:contactId"
  --data '{"firstName" : "John", "lastName" : "Doe" }'
  --user ":YourApiKey"
  -H "application/json"

The above command returns JSON structured like this:

{
    "_id": "uBJadNFcjrC6emRom",
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "nbRequest": 11,
    "tag": [ "Speaker" ],
    "custom": [
        {
            "_id": "yw6XDyeFvbqr86yA6",
            "name": "Favorite color",
            "variable": "color",
            "value": "Blue"
        },
        {
            "_id": "CqdFwGX3yitk9zf8z",
            "name": "Country",
            "variable": "country",
            "value": "US"
        }
    ],
    "createdAt": "2019-02-22T13:40:26.591Z",
    "lastActivity": "2019-06-19T17:14:52.498Z",
    "requests": [
        {
            "_id": "NxAHPWu9hRzcyD24m",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-02-22T13:40:26.671Z",
            "status": "completed",
            "privacy": "team",
            "branding": {
                "useBranding": false
            }
        },
        {
            "_id": "jP6sXJ72R8xjxceaP",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-04-19T13:58:07.310Z",
            "status": "completed",
            "privacy": "team",
            "branding": {
                "useBranding": false
            },
            "note": {
                "date": "2019-05-04T14:25:17.254Z",
                "note": "Asked him to send back another document"
            }
        },
        {
            "_id": "FmZNnerEFRF3dLYPK",
            "campaignId": "mYCsdgB4DQoENBaX6",
            "createdAt": "2019-06-18T16:19:46.420Z",
            "status": "pending",
            "privacy": "team",
            "branding": {
                "useBranding": true,
                "brandingId": "jSEj7vHk3wLG3gRF7"
            }
        }
    ]
}

This endpoint modify an existing contact. It returns the contact object.

HTTP Request

POST https://api.usecollect.com/v1/contacts/:contactId

URL Parameters

Parameter Description
contactId (Mandatory) Specify the ID of the contact to modify.

Body Parameters

Body is mandatory and must be a JSON object with the information you want to modify. If a key is not specify, it won't be modified. To delete an optional key, just set the value as null.

Parameter Description
firstName (Optional) Specify the firstName of the contact.
lastName (Optional) Specify the lastName of the contact.
email Specify the email of the contact. This paramater is optional (only if you want to modify the email address) but the key is mandatory and won't accept null as value.
tag (Optional) You can specify the tags you want to add to the contact. If you specify tags it will overwrite the existing list of tags.
customFields (Optional) You can modify the values of the custom fields by posting an array of object. To modify the value of a custom field, you need to specify the _id of the custom field or the variable. If you want to delete the value of a custom field for a contact, set null as a value. If you want to create a custom field that doesn't exist, you need to specify the variable (must be lowercase and without special caracter), the name and the value.

Notes

The list of requests is limited to 50 results.

Delete a contact

curl -X DELETE "https://api.usecollect.com/v1/contacts/:contactId"
  --user ":YourApiKey"

The above command returns JSON structured like this:

{
    "id": "gqKBB8ZD4aHiY4Cb2",
    "deleted": true
}

This endpoint delete an existing contact and all the requests linked to it. It returns an object with the contactId.

HTTP Request

DELETE https://api.usecollect.com/v1/contacts/:contactId

URL Parameters

Parameter Description
contactId (Mandatory) Specify the ID of the contact to delete.

Webhooks

You can configure webhook endpoints via the API to be notified about events that happen in your Collect account.

Notes

Collect attempts to deliver your webhooks for 24 hours with an exponential back off. After this timing, your webhook will automatically be paused.

List all webhook's endpoints

curl "https://api.usecollect.com/v1/webhooks"
  --user ":YourApiKey"

The above command returns JSON structured like this:

[
    {
        "_id": "HBsDeedGXx7BYbXwo",
        "targetUrl": "https://youserver.com/collect-hook",
        "status": "active",
        "createdAt": "2019-07-05T14:30:41.215Z",
        "secretToken": "gWg3fowgIgkc5KQvSojqWU"
    },
    {
        "_id": "mLASNBTu9n6vB6Zss",
        "targetUrl": "https://yourotheserver.com/collect-hook",
        "campaignId": "mYCsdgB4DQoENBaX6",
        "types": ["docUploaded","formSubmited"],
        "status": "active",
        "createdAt": "2019-07-06T15:21:15.655Z"
    }
]

This endpoint retrieves all your webhooks.

HTTP Request

GET https://api.usecollect.com/v1/webhooks

Add a webhook

curl -X POST "https://api.usecollect.com/v1/webhooks"
  --data '{"targetUrl": "https://ngrok.io/12232", "types": ["created","statusChanged","dueDateChanged"]}'
  --user ":YourApiKey"
  -H "application/json"

The above command returns JSON structured like this:

{
    "_id": "eqQkPdnqwN7J38QEx",
    "targetUrl": "https://ngrok.io/12232",
    "status": "active",
    "createdAt": "2019-07-13T15:01:38.219Z"
}

This endpoint add a new webhook. It returns the webhook object.

HTTP Request

POST https://api.usecollect.com/v1/webhooks

Body Parameters

Body is mandatory and must be a JSON object with the information you want to add.

Parameter Description
targetUrl (Mandatory) The URL of the webhook endpoint.
types (Optional) The list of events to enable for this endpoint. Will be triggered for all type of events if not specified. Type can be created,statusChanged,dueDateChanged, uploadPageViewed, docUploaded, docDeleted, docAccepted, docRejected, docReopened, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub
campaignId (Optional) We'll call this endpoint only for this campaignId.
secretToken (Optional) If you specify a secret token, it will be sent with the hook request in the HTTP header. Your webhook endpoint can check that to verify that the request is legitimate.

Modify a webhook

curl -X POST "https://api.usecollect.com/v1/webhooks/:webhookId"
  --data '{"status" : "active"}'
  --user ":YourApiKey"
  -H "application/json"

The above command returns JSON structured like this:

{
    "_id": "eqQkPdnqwN7J38QEx",
    "targetUrl": "https://ngrok.io/12232",
    "status": "active",
    "createdAt": "2019-07-13T15:01:38.219Z"
}

This endpoint modify an existing webhook. It returns the webhook object.

HTTP Request

POST https://api.usecollect.com/v1/webhooks/:webhookId

URL Parameters

Parameter Description
webhookId (Mandatory) Specify the ID of the webhook to modify.

Body Parameters

Body is mandatory and must be a JSON object with the information you want to modify. If a key is not specify, it won't be modified. To delete an optional key, just set the value as null.

Parameter Description
targetUrl Specify the targetUrl of the contact. This paramater is optional (only if you want to modify the url of the webhook endpoint) but the key is mandatory and won't accept null as value.
types (Optional) The list of events to enable for this endpoint. Will be triggered for all type of events if not specified. Type can be created,statusChanged,dueDateChanged, uploadPageViewed, docUploaded, docDeleted, docAccepted, docRejected, docReopened, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub
campaignId (Optional) We'll call this endpoint only for this campaignId.
secretToken (Optional) If you specify a secret token, it will be sent with the hook request in the HTTP header. Your webhook endpoint can check that to verify that the request is legitimate.
status (Optional) The status of the webhook. It can be active or paused.

Delete a webhook

curl -X DELETE "https://api.usecollect.com/v1/webhooks/:webhookId"
  --user ":YourApiKey"

The above command returns JSON structured like this:

{
    "id": "eqQkPdnqwN7J38QEx",
    "deleted": true
}

This endpoint delete an existing webhook. It returns an object with the webhookId.

HTTP Request

DELETE https://api.usecollect.com/v1/webhooks/:webhookId

URL Parameters

Parameter Description
webhookId (Mandatory) Specify the ID of the webhook to delete.

Errors

The Collect API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The object requested is hidden for administrators only.
404 Not Found -- The specified object could not be found.
429 Too Many Requests -- You're requesting too many objects! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.