Collect API
1.0

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.

This is the documentation for version 1.0 of the API. Last update on Mar 21, 2023.

Base URL 
https://api.usecollect.com/v1

Authentication

Basic auth (http)

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. username:password where the username is always empty and the password is the API key.

Don't forget to add the semicolon ( : ) before your API key in curl command.

Teams

Get Team Information

GET /team

This endpoint retrieves information of your team.

Responses

  • • 200 object

    Information of your team.

    • _id string
    • tz string

      The timezone associated to your account. We are using IANA time zone format. Ex: America/New_York for NYC.

    • name string
    • plan object
  • • 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.

GET /team 
curl \
 -X GET https://api.usecollect.com/v1/team \
 --user "username:password"
Response example (200) 
{
  "_id": "YcnS5JKMnG5cA3TXK",
  "tz": "America/New_York",
  "name": "ACME",
  "plan": {
    "name": "Business",
    "end": "2023-05-04T09:42:00+00:00"
  }
}

Users

List all users

GET /users

This endpoint retrieves all the users in your team.

Responses

  • • 200 array[object]

    List of users in your team.

  • • 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.

GET /users 
curl \
 -X GET https://api.usecollect.com/v1/users \
 --user "username:password"
Response example (200) 
[
  {
    "_id": "upKywNKgwyHx3hKfF",
    "role": "admin",
    "status": "active",
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  {
    "_id": "ABx6DYtqExcgJ4FAX,",
    "role": "member",
    "status": "active",
    "email": "janedoe@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  {
    "_id": "uSw8YyNuwhGmqEEKc",
    "role": "member",
    "status": "active",
    "email": "jimhuffman@example.com",
    "firstName": "Jim",
    "lastName": "Huffman"
  },
  {
    "_id": "RQEPygugi3Nk9Sudm",
    "role": "member",
    "status": "active",
    "email": "naomiaustin@example.com"
  }
]

Get a specific user

GET /user

This endpoint retrieves a specific user in your team. You can search by user ID or by email.

Query parameters

  • id string

    Use this parameter if you want to search by user ID.

  • email string

    Use this parameter if you want to search a user by email.

Responses

  • • 200 object

    A specific user.

  • • 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.

GET /user 
curl \
 -X GET https://api.usecollect.com/v1/user \
 --user "username:password"
Response example (200) 
{
  "_id": "upKywNKgwyHx3hKfF",
  "role": "admin",
  "status": "active",
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Campaigns

List all campaigns

GET /campaigns

This endpoint retrieves all the campaigns.

Query parameters

  • offset integer

    Specify the ranking number of the first item on the page. Used for pagination.

  • limit integer

    Specify how many results to return. Default is 50 campaigns, maximum is 100 campaigns.

    Maximum value is 100. Default value is 50.

  • showArchives boolean

    Specify if the archived campaigns should be included or not. Default is false.

Responses

  • • 200 array[object]

    List of campaigns.

    • _id string

      Unique identifier for the campaign

    • name string

      Name of the campaign

    • createdAt string(date-time)

      Creation date of the campaign

    • status string

      Status of the campaign

      Values are open, closed, or archived.

    • count object
      • request integer

        Number of request made

      • open integer

        Number of open requests

      • done integer

        Number of done requests

      • due integer

        Number of due requests

      • waiting integer

        Number of requests waiting for validation

      • error integer

        Number of requests with errors

      • message integer

        Number of message requests

  • • 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.

GET /campaigns 
curl \
 -X GET https://api.usecollect.com/v1/campaigns \
 --user "username:password"
Response example (200) 
[
  {
    "_id": "mYCsdgB4DQoENBaX6",
    "name": "ERC application",
    "createdAt": "2022-11-22 13:28:08 UTC",
    "status": "open",
    "count": {
      "request": 72,
      "open": 4,
      "done": 61,
      "due": 5,
      "waiting": 2,
      "error": 0,
      "message": 0
    }
  },
  {
    "_id": "wFndw23xmx5RdWrFX",
    "name": "Company KYC",
    "createdAt": "2023-01-31 09:49:25 UTC",
    "status": "open",
    "count": {
      "request": 22,
      "open": 4,
      "done": 18,
      "due": 0,
      "waiting": 0,
      "error": 0,
      "message": 0
    }
  }
]

Get a specific campaign

GET /campaigns/{campaignId}

Retrieve all the details of a specific campaign.

Path parameters

  • campaignId string Required

    The ID of the campaign to retrieve.

Responses

  • • 200 object

    Campaign details

  • • 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.

GET /campaigns/{campaignId} 
curl \
 -X GET https://api.usecollect.com/v1/campaigns/{campaignId} \
 --user "username:password"
Response example (200) 
{
  "_id": "DP7Sj7stsmXbKCKbK",
  "createdAt": "2022-12-22 14:24:29 UTC",
  "status": "open",
  "documents": [
    {
      "id": "Gwm5sHv6tzikK65We",
      "name": "ID",
      "order": 0,
      "mandatory": false,
      "multipleupload": true
    },
    {
      "id": "4PQd5HKQcBk5BZmsB",
      "name": "Bank statement",
      "order": "1,",
      "mandatory": true,
      "extensions": [
        "pdf"
      ],
      "multipleupload": true
    }
  ],
  "forms": [
    {
      "id": "sDmmcMFRRbnizYsQp",
      "name": "Client contacts",
      "order": 3,
      "items": [
        {
          "id": "6878fzc9KPi9ZkMPG",
          "name": "First Name",
          "type": "shortText"
        },
        {
          "id": "sAEPkpyYr7SRisJWv",
          "name": "Last Name",
          "type": "shortText"
        },
        {
          "id": "F3ov9Qnr2zPJNKkL8",
          "name": "Business Industry",
          "type": "multi"
        }
      ]
    }
  ],
  "texts": [
    {
      "id": "2qcE5ibXgdkjvpkp2",
      "name": "Text block",
      "order": 4
    }
  ],
  "pages": [
    {
      "id": "DCd4FDZ5EBN2pgWmj",
      "name": "Details",
      "order": 2
    }
  ]
}

Requests

List all the requests of a campaign

GET /requests

This endpoint retrieves all the requests of a campaign.

Query parameters

  • campaignId string Required

    Specify the ID of the campaign to retrieve.

  • offset integer

    Specify the ranking number of the first item on the page. Used for pagination.

  • limit integer

    Specify how many results to return. Default is 50 campaigns, maximum is 100 campaigns.

    Maximum value is 100. Default value is 50.

  • filter string

    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 and the forms submitted. If validation is opted-in, the documents and data 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 and the forms submitted 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.

    You can also use custom status here.

Responses

GET /requests 
curl \
 -X GET https://api.usecollect.com/v1/requests?campaignId=mYCsdgB4DQoENBaX6 \
 --user "username:password"
Response example (200) 
[
  {
    "_id": "NxAHPWu9hRzcyD24m",
    "campaignId": "mYCsdgB4DQoENBaX6",
    "createdAt": "2022-05-22 13:40:26 UTC",
    "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/NxAHPWu9hRzcyD24m",
    "status": "due",
    "dueDate": "2022-06-12 22:59:00 UTC",
    "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-22 13:40:26 UTC",
      "lastActivity": "2021-06-17 17:14:52 UTC"
    },
    "branding": {
      "useBranding": true,
      "brandingId": "jSEj7vHk3wLG3gRF7"
    }
  }
]

Send multiple requests

POST /requests

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

Body

  • campaignId string Required

    The ID of the campaign you want to send a request.

  • contacts array[string] | array[object] Required
    One of:
    Contact Id array[string] Contact Object array[object]

    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)

  • items array[string]

    An array of itemId. If you want to request only few items (documents and forms) of the campaign, you can optionaly specify which items you want to retrieve.

  • samples object

    An array of object. Each object represents the sample of a document element. The object must contain 2 parameters: 'itemId' and 'url'.

  • sendMessage boolean

    Boolean. If set to false, the sequence of messages planned in your campaign will not be sent.

Responses

POST /requests 
curl \
 -X POST https://api.usecollect.com/v1/requests \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"campaignId":"xvr69EYLKXvTkfYuk","contacts":["WmTjsFknzHdmfs3Ra",{"email":"elon@example.com","firstName":"Elon","lastName":"Musk"}]}'
Request example 
{
  "campaignId": "xvr69EYLKXvTkfYuk",
  "contacts": [
    "WmTjsFknzHdmfs3Ra",
    {
      "email": "elon@example.com",
      "firstName": "Elon",
      "lastName": "Musk"
    }
  ]
}
Response example (200) 
{
  "requests": [
    {
      "_id": "nw42MmBsJoccgutST",
      "campaignId": "xvr69EYLKXvTkfYuk",
      "createdAt": "2022-07-04 07:20:06 UTC",
      "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/nw42MmBsJoccgutST",
      "status": "pending",
      "dueDate": "2022-07-11 21:59:00 UTC",
      "privacy": "private",
      "contact": {
        "_id": "WmTjsFknzHdmfs3Ra",
        "email": "johndoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "nbRequest": 5,
        "createdAt": "2022-07-03 13:51:27 UTC",
        "lastActivity": "2022-07-04 07:20:06 UTC"
      },
      "branding": {
        "useBranding": false
      }
    },
    {
      "_id": "jdDzbxP8MnfBdrRuM",
      "campaignId": "xvr69EYLKXvTkfYuk",
      "createdAt": "2022-07-04 07:20:06 UTC",
      "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/jdDzbxP8MnfBdrRuM",
      "status": "pending",
      "dueDate": "2022-07-11 21:59:00 UTC",
      "privacy": "private",
      "contact": {
        "_id": "ngxhLDiDGEBS2jjKh",
        "email": "elon@example.com",
        "firstName": "Elon",
        "lastName": "Musk",
        "nbRequest": 1,
        "createdAt": "2022-07-04 07:20:06 UTC",
        "lastActivity": "2022-07-04 07:20:06 UTC"
      },
      "branding": {
        "useBranding": false
      }
    }
  ],
  "contacts": [
    "WmTjsFknzHdmfs3Ra",
    {
      "_id": "ngxhLDiDGEBS2jjKh",
      "email": "elon@example.com",
      "firstName": "Elon",
      "lastName": "Musk",
      "createdAt": "2022-07-04 07:20:06 UTC"
    }
  ],
  "errors": []
}

Get a specific request

GET /requests/{requestId}

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

Path parameters

  • requestId string Required

    The ID of the request to retrieve.

Query parameters

  • expires integer

    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).

Responses

GET /requests/{requestId} 
curl \
 -X GET https://api.usecollect.com/v1/requests/{requestId} \
 --user "username:password"
Response example (200) 
{
  "_id": "NxAHPWu9hRzcyD24m",
  "campaignId": "mYCsdgB4DQoENBaX6",
  "createdAt": "2020-01-22 13:40:26 UTC",
  "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/NxAHPWu9hRzcyD24m",
  "status": "due",
  "dueDate": "2020-01-29 22:59:00 UTC",
  "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": "2021-11-22 13:40:26 UTC",
    "lastActivity": "2020-01-24 17:14:52 UTC"
  },
  "branding": {
    "useBranding": true,
    "brandingId": "jSEj7vHk3wLG3gRF7"
  },
  "documents": [
    {
      "id": "dfgZmo7SdijHMkwx5",
      "itemId": "gKLyBTL3RyzqTnoHc",
      "name": "ID",
      "status": "waiting",
      "order": 1,
      "visibility": true,
      "extensions": [
        "pdf"
      ],
      "multipleupload": true,
      "uploads": [
        {
          "createdAt": "2020-01-23 14:01:31 UTC",
          "name": "Elon's ID.pdf",
          "url": "https://collectuseast.s3.amazonaws.com/elon_id.pdf?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=bglKxNBqqcDKkAeuzmxoBS2IOQQ%3D",
          "size": 2414511
        }
      ]
    },
    {
      "id": "MnDf76Dmp9LzG32PG",
      "itemId": "rpBjtem4kkPnFa3rH",
      "name": "Bank statement",
      "status": "waiting",
      "order": 2,
      "visibility": true,
      "extensions": [
        "zip",
        "rar",
        "gzip",
        "gz"
      ],
      "multipleupload": true,
      "sample": {
        "name": "bank_statement.pdf",
        "url": "https://collectsamples.s3.amazonaws.com/bank_statement.pdf"
      },
      "uploads": [
        {
          "createdAt": "2020-01-23 15:59:36 UTC",
          "name": "bank_statement.zip",
          "url": "https://collectuseast.s3.amazonaws.com/bank_statement.zip?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=FRsF%2FP7QFIUyQ2PIRHn0NidCivI%3D",
          "size": 42573459
        }
      ]
    }
  ],
  "forms": [
    {
      "id": "BWXwpuhhjkoJ4PyBt",
      "itemId": "buBLLGP3WczFCrNBh",
      "name": "Client contacts",
      "status": "completed",
      "order": 0,
      "visibility": true,
      "items": [
        {
          "name": "First Name",
          "type": "shortText",
          "answer": "Elon"
        },
        {
          "name": "Last Name",
          "type": "shortText",
          "answer": "Musk"
        },
        {
          "name": "Business industry",
          "type": "multi",
          "answer": [
            "Cars",
            "Space"
          ]
        }
      ]
    }
  ]
}

Send a new request

POST /request

This endpoint allows you to send a new request to a new contacts or to an existing contact.

Body

Responses

POST /request 
curl \
 -X POST https://api.usecollect.com/v1/request \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"campaignId":"xvr69EYLKXvTkfYuk","contact":{"email":"elon@example.com","firstName":"Elon","lastName":"Musk","data":{"brand":"Tesla","model":"Roadster"}}}'
Request examples 
{
  "campaignId": "xvr69EYLKXvTkfYuk",
  "contact": {
    "email": "elon@example.com",
    "firstName": "Elon",
    "lastName": "Musk",
    "data": {
      "brand": "Tesla",
      "model": "Roadster"
    }
  }
}
{
  "campaignId": "xvr69EYLKXvTkfYuk",
  "contact": "WmTjsFknzHdmfs3Ra"
}
Response example (200) 
{
  "request": {
    "_id": "nw42MmBsJoccgutST",
    "campaignId": "xvr69EYLKXvTkfYuk",
    "createdAt": "2022-07-04 07:20:06 UTC",
    "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/nw42MmBsJoccgutST",
    "status": "pending",
    "dueDate": "2022-07-11 21:59:00 UTC",
    "privacy": "private",
    "contact": {
      "_id": "WmTjsFknzHdmfs3Ra",
      "email": "johndoe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "nbRequest": 5,
      "createdAt": "2022-07-03 13:51:27 UTC",
      "lastActivity": "2022-07-04 07:20:06 UTC"
    },
    "branding": {
      "useBranding": false
    }
  },
  "errors": []
}

Modify a request

PATCH /request

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

Body

  • requestId string

    The ID of the request you want to modify.

  • status string

    The new status of the request. Can be one of the predifined status pending, completed, waiting, canceled, archived or a custom status that you previously have created on your account.

  • dueDate string

    The new due date of the request. The due date should be encoded as a string using ISO 8601 format.

  • data object

    An object with custom data that you want to use in your request.

  • assignedTo string

    The ID of the team member you want to assign the request to. Use 'unset' if you want to unassign the request.

Responses

PATCH /request 
curl \
 -X PATCH https://api.usecollect.com/v1/request \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"requestId":"bbbBkrejSaJkHWwDE","status":"pending"}'
Request example 
{
  "requestId": "bbbBkrejSaJkHWwDE",
  "status": "pending"
}
Response example (200) 
{
  "request": {
    "_id": "bbbBkrejSaJkHWwDE",
    "campaignId": "7gDq3XyLyixkhqoHa",
    "createdAt": "2023-02-21 10:31:52 UTC",
    "status": "pending",
    "dueDate": null,
    "portalUrl": "https://app.usecollect.com/portal/LzP5r56tpqh3gteCf/bbbBkrejSaJkHWwDE",
    "privacy": "private",
    "contact": {
      "_id": "ngxhLDiDGEBS2jjKh",
      "email": "elon@example.com",
      "firstName": "Elon",
      "lastName": "Musk",
      "tag": [],
      "custom": [],
      "createdAt": "2022-11-16 05:00:43 UTC",
      "lastActivity": "2022-02-21 10:31:52 UTC"
    },
    "branding": {
      "useBranding": true,
      "brandingId": "bJoTr6kHikTRDsvSd"
    }
  },
  "errors": []
}

Add a contributor

POST /contributors

This endpoint allows you to add new contacts or existing contacts as contributors of a request.

Body

Responses

POST /contributors 
curl \
 -X POST https://api.usecollect.com/v1/contributors \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"requestId":"xvr69EYLKXvTkfYuk","contact":{"email":"elon@example.com","firstName":"Elon","lastName":"Musk","data":{"brand":"Tesla","model":"Roadster"}}}'
Request examples 
{
  "requestId": "xvr69EYLKXvTkfYuk",
  "contact": {
    "email": "elon@example.com",
    "firstName": "Elon",
    "lastName": "Musk",
    "data": {
      "brand": "Tesla",
      "model": "Roadster"
    }
  }
}
{
  "requestId": "xvr69EYLKXvTkfYuk",
  "contact": "WmTjsFknzHdmfs3Ra"
}
Response example (200) 
{
  "request": {
    "_id": "nw42MmBsJoccgutST",
    "campaignId": "xvr69EYLKXvTkfYuk",
    "createdAt": "2022-07-04 07:20:06 UTC",
    "portalUrl": "https://app.usecollect.com/portal/uGFRDeEL3Ct2uYo2c/nw42MmBsJoccgutST",
    "status": "pending",
    "dueDate": "2022-07-11 21:59:00 UTC",
    "privacy": "private",
    "contact": {
      "_id": "xtPWKQqcAk8MJfoz5",
      "email": "maincontact@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "nbRequest": 5,
      "createdAt": "2022-07-03 13:51:27 UTC",
      "lastActivity": "2022-07-04 07:20:06 UTC"
    },
    "contributors": [
      {
        "_id": "WmTjsFknzHdmfs3Ra",
        "email": "johndoe@example.com",
        "firstName": "Elon",
        "lastName": "Musk",
        "createdAt": "2022-07-03 13:51:27 UTC"
      }
    ],
    "branding": {
      "useBranding": false
    }
  },
  "errors": []
}

Remove a contributor

DELETE /contributors/{requestId}

This endpoint remove an existing contributor from a request. You need to specify the contactId or the email of the contact. It returns an object with the requestId and the contactId.

This action can't be cancelled. Use it at your own risk.

Path parameters

  • requestId string Required

    Specify the ID of the request.

  • contactId string

    Specify the ID of the contact to remove.

  • email string

    Specify the email of the contact to remove.

Responses

  • • 200 object
  • • 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.

DELETE /contributors/{requestId} 
curl \
 -X DELETE https://api.usecollect.com/v1/contributors/{requestId} \
 --user "username:password"
Response example (200) 
{
  "id": "XigRzPs4N5vwX3Rks",
  "contactId": "SSKm6i9cxbvZuLRDB",
  "deleted": true
}

Elements

Get a specific element

GET /elements/{elementId}

This endpoint retrieves all the details of a specific element including the answers of the forms and the documents that have been uploaded.

Path parameters

  • elementId string Required

    The ID of the element to retrieve

Query parameters

  • expires integer

    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).

Responses

GET /elements/{elementId} 
curl \
 -X GET https://api.usecollect.com/v1/elements/{elementId} \
 --user "username:password"
Response examples (200) 
{
  "id": "eEDJFD5unNQTHoSBZ",
  "itemId": "urRJfPK7CfyGBnHg8",
  "name": "ID",
  "order": 3,
  "visibility": true,
  "status": "approved",
  "mandatory": true,
  "multipleupload": true,
  "uploads": [
    {
      "createdAt": "2022-02-21 11:27:32 UTC",
      "name": "Elon's ID.pdf",
      "url": "https://collectuseast.s3.amazonaws.com/elon_id.pdf?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=bglKxNBqqcDKkAeuzmxoBS2IOQQ%3D",
      "size": 2414511
    }
  ],
  "type": "docs",
  "request": {
    "_id": "bbbBkrejSaJkHWwDE",
    "campaignId": "7gDq3XyLyixkhqoHa"
  }
}
{
  "id": "2ewEw5L6amQiJ6J2A",
  "itemId": "dy8SYGJauWwhDcGrp",
  "name": "Company info",
  "order": 0,
  "visibility": true,
  "status": "open",
  "items": [
    {
      "name": "What size is your company",
      "type": "dropdown",
      "answer": "50-250 employees"
    },
    {
      "name": "Where is your company located?",
      "type": "multi",
      "answer": [
        "🇺🇸 USA",
        "🇪🇺 Europe"
      ]
    }
  ],
  "type": "form",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}
{
  "id": "BKJ95xmpHSyo7KuRC",
  "itemId": "7LBBC8LwnBnQoz8ae",
  "name": "Text block",
  "order": 4,
  "visibility": true,
  "type": "text",
  "text": "Hello World!",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}
{
  "id": "XigRzPs4N5vwX3Rks",
  "itemId": "L3uAmzDRJjWTm2TMR",
  "name": "More details",
  "order": 2,
  "visibility": true,
  "type": "page",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}

Delete an element

DELETE /elements/{elementId}

This endpoint delete an existing element and all the answers / documents linked to it. It returns an object with the elementId.

This action can't be cancelled. Use it at your own risk.

Path parameters

  • elementId string Required

    Specify the ID of the element to delete.

Responses

  • • 200 object
  • • 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.

DELETE /elements/{elementId} 
curl \
 -X DELETE https://api.usecollect.com/v1/elements/{elementId} \
 --user "username:password"
Response example (200) 
{
  "id": "XigRzPs4N5vwX3Rks",
  "deleted": true
}

Add an element

POST /elements

This endpoint allows you to add an element to an existing request. You can currently add docs, text and pages. form will come later.

Body object

One of:
Document object Text object Page object

Responses

POST /elements 
curl \
 -X POST https://api.usecollect.com/v1/elements \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"requestId":"bbbBkrejSaJkHWwDE","type":"docs","name":"ID","order":3}'
Request examples 
{
  "requestId": "bbbBkrejSaJkHWwDE",
  "type": "docs",
  "name": "ID",
  "order": 3
}
{
  "requestId": "GTonevwqoPPJ2PYEy",
  "type": "text",
  "order": 4,
  "text": "Hello World!"
}
{
  "requestId": "GTonevwqoPPJ2PYEy",
  "type": "page",
  "order": 2,
  "name": "More details"
}
Response examples (200) 
{
  "id": "eEDJFD5unNQTHoSBZ",
  "itemId": "urRJfPK7CfyGBnHg8",
  "name": "ID",
  "order": 3,
  "visibility": true,
  "status": "open",
  "mandatory": true,
  "multipleupload": true,
  "uploads": [],
  "type": "docs",
  "request": {
    "_id": "bbbBkrejSaJkHWwDE",
    "campaignId": "7gDq3XyLyixkhqoHa"
  }
}
{
  "id": "BKJ95xmpHSyo7KuRC",
  "itemId": "7LBBC8LwnBnQoz8ae",
  "name": "Text block",
  "order": 4,
  "visibility": true,
  "type": "text",
  "text": "Hello World!",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}
{
  "id": "XigRzPs4N5vwX3Rks",
  "itemId": "L3uAmzDRJjWTm2TMR",
  "name": "More details",
  "order": 2,
  "visibility": true,
  "type": "page",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}

Modify an element

PATCH /elements

This endpoint allows you to modify an element of a request.

Body object

One of:
Document object Page object Text object Page object

Responses

PATCH /elements 
curl \
 -X PATCH https://api.usecollect.com/v1/elements \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"elementId":"eEDJFD5unNQTHoSBZ","status":"rejected","reason":"The document is not readable"}'
Request examples 
{
  "elementId": "eEDJFD5unNQTHoSBZ",
  "status": "rejected",
  "reason": "The document is not readable"
}
{
  "requestId": "2ewEw5L6amQiJ6J2A",
  "status": "approved",
  "visibility": false
}
{
  "requestId": "BKJ95xmpHSyo7KuRC",
  "type": "text",
  "order": 4,
  "text": "Hello everyone!"
}
{
  "requestId": "XigRzPs4N5vwX3Rks",
  "type": "page",
  "order": 3,
  "name": "More details"
}
Response examples (200) 
{
  "id": "eEDJFD5unNQTHoSBZ",
  "itemId": "urRJfPK7CfyGBnHg8",
  "name": "ID",
  "order": 3,
  "visibility": true,
  "status": "rejected",
  "reason": "The document is not readable",
  "mandatory": true,
  "multipleupload": true,
  "uploads": [
    {
      "createdAt": "2022-02-21 11:27:32 UTC",
      "name": "Elon's ID.pdf",
      "url": "https://collectuseast.s3.amazonaws.com/elon_id.pdf?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1561559790&Signature=bglKxNBqqcDKkAeuzmxoBS2IOQQ%3D",
      "size": 2414511
    }
  ],
  "type": "docs",
  "request": {
    "_id": "bbbBkrejSaJkHWwDE",
    "campaignId": "7gDq3XyLyixkhqoHa"
  }
}
{
  "id": "2ewEw5L6amQiJ6J2A",
  "itemId": "dy8SYGJauWwhDcGrp",
  "name": "Company info",
  "order": 0,
  "visibility": false,
  "status": "approved",
  "items": [
    {
      "name": "What size is your company",
      "type": "dropdown",
      "answer": "50-250 employees"
    },
    {
      "name": "Where is your company located?",
      "type": "multi",
      "answer": [
        "🇺🇸 USA",
        "🇪🇺 Europe"
      ]
    }
  ],
  "type": "form",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}
{
  "id": "BKJ95xmpHSyo7KuRC",
  "itemId": "7LBBC8LwnBnQoz8ae",
  "name": "Text block",
  "order": 4,
  "visibility": true,
  "type": "text",
  "text": "Hello everyone!",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}
{
  "id": "XigRzPs4N5vwX3Rks",
  "itemId": "L3uAmzDRJjWTm2TMR",
  "name": "More details",
  "order": 3,
  "visibility": true,
  "type": "page",
  "request": {
    "_id": "GTonevwqoPPJ2PYEy",
    "campaignId": "3ya2sjN9GYwYAHeSi"
  }
}

Upload a file

POST /upload

This endpoint allows you to upload a file to a doc element. You can upload a remote file using the url parameter or a file encoded in base64 using the data parameter.

Body

  • elementId string

    ID of the doc element you want to upload the file to

  • url string

    URL of the remote file. The file size is limited to 20Mb.

  • data string

    Base64 encoded file. The file size is limited to 20Mb.

  • name string

    Name of the file with the file extension.

Responses

  • • 200 object
  • • 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.

POST /upload 
curl \
 -X POST https://api.usecollect.com/v1/upload \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"elementId":"eEDJFD5unNQTHoSBZ","url":"https://randomremoteserver.com/whitepaper.pdf","name":"whitepaper.pdf"}'
Request example 
{
  "elementId": "eEDJFD5unNQTHoSBZ",
  "url": "https://randomremoteserver.com/whitepaper.pdf",
  "name": "whitepaper.pdf"
}
Response example (200) 
{
  "id": "eEDJFD5unNQTHoSBZ",
  "itemId": "urRJfPK7CfyGBnHg8",
  "name": "ID",
  "order": 3,
  "visibility": true,
  "status": "open",
  "mandatory": true,
  "multipleupload": true,
  "uploads": {
    "id": "z2A3thsdGaLSidmQq",
    "createdAt": "2023-01-31 06:53:36 UTC",
    "name": "whitepaper.pdf",
    "url": "https://collectuseast.s3.amazonaws.com/samples/business_plan_acme.pdf?AWSAccessKeyId=AKIAJTQD6LRBSTO25FSQ&Expires=1675693205&Signature=tS9MixgslTykB6fKE8aFTqArzek%3D",
    "size": 344701
  },
  "type": "docs",
  "request": {
    "_id": "bbbBkrejSaJkHWwDE",
    "campaignId": "7gDq3XyLyixkhqoHa"
  }
}

Contacts

List all contacts

GET /contacts

Retrieve all contacts shared by the team

Query parameters

  • offset integer

    Ranking number of the first item on the page

  • limit integer

    Number of results to return

    Maximum value is 100. Default value is 50.

  • sort string

    Specify how to sort the results

    Values are fnAsc, fnDesc, lnAsc, lnDesc, emAsc, emDesc, tagAsc, or tagDesc.

  • search string

    String to look up

Responses

  • • 200 array[object]

    Success

  • • 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.

GET /contacts 
curl \
 -X GET https://api.usecollect.com/v1/contacts \
 --user "username:password"
Response example (200) 
[
  {
    "_id": "uBJadNFcjrC6emRom",
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "tag": [
      "Speaker"
    ],
    "custom": [
      {
        "_id": "yw6XDyeFvbqr86yA6",
        "name": "Favorite color",
        "variable": "color",
        "value": "Blue"
      },
      {
        "_id": "CqdFwGX3yitk9zf8z",
        "name": "Country",
        "variable": "country",
        "value": "US"
      }
    ]
  }
]

Add a contact

POST /contacts

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

Body Required

Responses

POST /contacts 
curl \
 -X POST https://api.usecollect.com/v1/contacts \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"email":"john@example.com","firstName":"John","lastName":"Doe","tags":["Speaker"],"customFields":[{"variable":"color","value":"Blue"},{"variable":"country","value":"US"}]}'
Request example 
{
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tags": [
    "Speaker"
  ],
  "customFields": [
    {
      "variable": "color",
      "value": "Blue"
    },
    {
      "variable": "country",
      "value": "US"
    }
  ]
}
Response example (200) 
{
  "_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": "2023-02-22 13:40:26 UTC",
  "requests": []
}

Get a specific contact

GET /contacts/{contactId}

This endpoint retrieves a specific request.

The list of requests is limited to 50 results.

Path parameters

  • contactId string Required

    Specify the ID of the contact to retrieve.

Responses

GET /contacts/{contactId} 
curl \
 -X GET https://api.usecollect.com/v1/contacts/{contactId} \
 --user "username:password"
Response example (200) 
{
  "_id": "uBJadNFcjrC6emRom",
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tag": [
    "Speaker"
  ],
  "custom": [
    {
      "_id": "yw6XDyeFvbqr86yA6",
      "name": "Favorite color",
      "variable": "color",
      "value": "Blue"
    },
    {
      "_id": "CqdFwGX3yitk9zf8z",
      "name": "Country",
      "variable": "country",
      "value": "US"
    }
  ],
  "createdAt": "2022-02-22 13:40:26 UTC",
  "lastActivity": "2022-06-19 17:14:52 UTC",
  "requests": [
    {
      "_id": "NxAHPWu9hRzcyD24m",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-02-22 13:40:26 UTC",
      "status": "completed",
      "privacy": "team",
      "branding": {
        "useBranding": false
      }
    },
    {
      "_id": "jP6sXJ72R8xjxceaP",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-04-19 13:58:07 UTC",
      "status": "completed",
      "privacy": "team",
      "branding": {
        "useBranding": false
      },
      "note": {
        "date": "2022-05-04 14:25:17 UTC",
        "note": "Asked him to send back another document"
      }
    },
    {
      "_id": "FmZNnerEFRF3dLYPK",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-06-18 16:19:46 UTC",
      "status": "pending",
      "privacy": "team",
      "branding": {
        "useBranding": true,
        "brandingId": "jSEj7vHk3wLG3gRF7"
      }
    }
  ]
}

Modify a contact

POST /contacts/{contactId}

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

Path parameters

  • contactId string Required

    Specify the ID of the contact to modify.

Body Required

Responses

POST /contacts/{contactId} 
curl \
 -X POST https://api.usecollect.com/v1/contacts/{contactId} \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"firstName":"John","lastName":"Doe","customFields":[{"variable":"color","value":"Blue"},{"variable":"country","value":"US"}]}'
Request example 
{
  "firstName": "John",
  "lastName": "Doe",
  "customFields": [
    {
      "variable": "color",
      "value": "Blue"
    },
    {
      "variable": "country",
      "value": "US"
    }
  ]
}
Response example (200) 
{
  "_id": "uBJadNFcjrC6emRom",
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tag": [
    "Speaker"
  ],
  "custom": [
    {
      "_id": "yw6XDyeFvbqr86yA6",
      "name": "Favorite color",
      "variable": "color",
      "value": "Blue"
    },
    {
      "_id": "CqdFwGX3yitk9zf8z",
      "name": "Country",
      "variable": "country",
      "value": "US"
    }
  ],
  "createdAt": "2022-02-22 13:40:26 UTC",
  "lastActivity": "2022-06-19 17:14:52 UTC",
  "requests": [
    {
      "_id": "NxAHPWu9hRzcyD24m",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-02-22 13:40:26 UTC",
      "status": "completed",
      "privacy": "team",
      "branding": {
        "useBranding": false
      }
    },
    {
      "_id": "jP6sXJ72R8xjxceaP",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-04-19 13:58:07 UTC",
      "status": "completed",
      "privacy": "team",
      "branding": {
        "useBranding": false
      },
      "note": {
        "date": "2022-05-04 14:25:17 UTC",
        "note": "Asked him to send back another document"
      }
    },
    {
      "_id": "FmZNnerEFRF3dLYPK",
      "campaignId": "mYCsdgB4DQoENBaX6",
      "createdAt": "2022-06-18 16:19:46 UTC",
      "status": "pending",
      "privacy": "team",
      "branding": {
        "useBranding": true,
        "brandingId": "jSEj7vHk3wLG3gRF7"
      }
    }
  ]
}

Delete a contact

DELETE /contacts/{contactId}

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

This action can't be cancelled. Use it at your own risk.

Path parameters

  • contactId string Required

    Specify the ID of the contact to delete.

Responses

  • • 200 object

    Success

  • • 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.

DELETE /contacts/{contactId} 
curl \
 -X DELETE https://api.usecollect.com/v1/contacts/{contactId} \
 --user "username:password"
Response example (200) 
{
  "id": "gqKBB8ZD4aHiY4Cb2",
  "deleted": true
}

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

GET /webhooks

This endpoint retrieves all your webhooks.

Responses

  • • 200 array[object]

    List of webhooks

    • _id string

      Unique identifier of the webhook

    • targetUrl string

      URL to which the webhook will send the data

    • status string

      Status of the webhook

    • createdAt string(date-time)

      Creation date of the webhook

    • secretToken string

      Secret token of the webhook

    • campaignId string

      Unique identifier of the campaign associated with the webhook

    • types array[string]

      Types of events that trigger the webhook

  • • 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.

GET /webhooks 
curl \
 -X GET https://api.usecollect.com/v1/webhooks \
 --user "username:password"
Response example (200) 
[
  {
    "_id": "HBsDeedGXx7BYbXwo",
    "targetUrl": "https://youserver.com/collect-hook",
    "status": "active",
    "createdAt": "2022-07-05 14:30:41 UTC",
    "secretToken": "gWg3fowgIgkc5KQvSojqWU"
  },
  {
    "_id": "mLASNBTu9n6vB6Zss",
    "targetUrl": "https://yourserver.com/collect-hook-two",
    "campaignId": "mYCsdgB4DQoENBaX6",
    "types": [
      "docUploadedformSubmited"
    ],
    "status": "active",
    "createdAt": "2022-07-06 15:21:15 UTC"
  }
]

Add a webhook

POST /webhooks

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

Body Required

  • targetUrl string Required

    The URL of the webhook endpoint.

  • types array[string]

    The list of events to enable for this endpoint.

    Values are created, statusChanged, portalSubmited, dueDateChanged, portalViewed, docUploaded, docDeleted, itemApproved, itemRejected, itemReopened, itemCancelValidation, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub, smsSent, smsDelivered, smsClicked, smsFailed, or smsUndelivered.

  • campaignId string

    We'll call this endpoint only for this campaignId.

  • secretToken string

    If you specify a secret token, it will be sent with the hook request in the HTTP header.

Responses

  • • 200 object

    Success

    • _id string
    • targetUrl string
    • status string
    • createdAt string(date-time)
    • types array[string]

      Values are created, statusChanged, portalSubmited, dueDateChanged, portalViewed, docUploaded, docDeleted, itemApproved, itemRejected, itemReopened, itemCancelValidation, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub, smsSent, smsDelivered, smsClicked, smsFailed, or smsUndelivered.

    • campaignId string

      We'll call this endpoint only for this campaignId.

    • secretToken string

      If you specify a secret token, it will be sent with the hook request in the HTTP header.

  • • 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.

POST /webhooks 
curl \
 -X POST https://api.usecollect.com/v1/webhooks \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"targetUrl":"https://yourserver.com/collect-hook","types":["created","statusChanged","dueDateChanged"],"campaignId":"sGyGrNPDxQDy6ZRAm"}'
Request example 
{
  "targetUrl": "https://yourserver.com/collect-hook",
  "types": [
    "created",
    "statusChanged",
    "dueDateChanged"
  ],
  "campaignId": "sGyGrNPDxQDy6ZRAm"
}
Response example (200) 
{
  "_id": "eqQkPdnqwN7J38QEx",
  "targetUrl": "https://yourserver.com/collect-hook",
  "status": "active",
  "types": [
    "created",
    "statusChanged",
    "dueDateChanged"
  ],
  "createdAt": "2022-07-13 15:01:38 UTC"
}

Modify a webhook

POST /webhooks/{webhookId}

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

Path parameters

  • webhookId string Required

    Specify the ID of the webhook to modify.

Body

  • targetUrl string Required

    The URL of the webhook endpoint.

  • types array[string]

    The list of events to enable for this endpoint.

    Values are created, statusChanged, portalSubmited, dueDateChanged, portalViewed, docUploaded, docDeleted, itemApproved, itemRejected, itemReopened, itemCancelValidation, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub, smsSent, smsDelivered, smsClicked, smsFailed, or smsUndelivered.

  • campaignId string

    We'll call this endpoint only for this campaignId.

  • secretToken string

    If you specify a secret token, it will be sent with the hook request in the HTTP header.

  • status string

    The status of the webhook. It can be active or paused

    Values are active or paused.

Responses

  • • 200 object

    Success

    • _id string
    • targetUrl string
    • status string
    • createdAt string(date-time)
    • types array[string]

      Values are created, statusChanged, portalSubmited, dueDateChanged, portalViewed, docUploaded, docDeleted, itemApproved, itemRejected, itemReopened, itemCancelValidation, formSubmited, emailSent, emailClicked, emailBounced, emailOpened, emailMarkedAsSpam, emailBlocked, emailUnsub, smsSent, smsDelivered, smsClicked, smsFailed, or smsUndelivered.

    • campaignId string

      We'll call this endpoint only for this campaignId.

    • secretToken string

      If you specify a secret token, it will be sent with the hook request in the HTTP header.

  • • 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.

POST /webhooks/{webhookId} 
curl \
 -X POST https://api.usecollect.com/v1/webhooks/{webhookId} \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"status":"paused"}'
Request example 
{
  "status": "paused"
}
Response example (200) 
{
  "_id": "eqQkPdnqwN7J38QEx",
  "targetUrl": "https://yourserver.com/collect-hook",
  "status": "paused",
  "types": [
    "created",
    "statusChanged",
    "dueDateChanged"
  ],
  "createdAt": "2022-07-13 15:01:38 UTC"
}

Delete webhook

DELETE /webhooks/{webhookId}

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

Path parameters

  • webhookId string Required

    Specify the ID of the webhook to delete.

Responses

  • • 200 object

    Success

  • • 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.

DELETE /webhooks/{webhookId} 
curl \
 -X DELETE https://api.usecollect.com/v1/webhooks/{webhookId} \
 --user "username:password"
Response example (200) 
{
  "id": "eqQkPdnqwN7J38QEx",
  "deleted": true
}