Bulk Create Leads

POST https://api.copper.com/developer_api/v1/leads/bulk_create

BETA Disclaimer ⚠️

Please note that our new bulk create/update APIs (including this one) are still undergoing final testing before their official release. We reserve the right to increase or decrease the maximum request size of these APIs (see the Request Size Limit section). Should you encounter any issues, please let us know so we can diagnose and resolve them. Your help in this regard is greatly appreciated.

Request Size Limit

This is a bulk-create endpoint with a maximum request size of 10. If you sent a request larger than that limit, you will receive a 422 back with response:

{
  "error": "Request size too large, limit is 10"
}

Responses

All valid requests (JSON is formatted correctly on request) will result in a 200 OK. Bulk APIs guarantee the same response object ordering as the request objects meaning you can match each response object up to the request's objects easily.

If an object is created successfully, it will be returned in the response array in the same JSON structure you would expect from the single-create endpoint. The key thing to look for is a present and numeric "id" value.

If an object fails to create, it's response object (within the response array) will look like this:

{
  "success": false,
  "message": {
    "name": [
      {
        "error": "invalid"
      }
    ]
  }
}

Notes

Some other notes about this bulk API: * This endpoint is eligible to return computed custom field values, click here for more information. * Our bulk APIs have an additional rate limit of 3 requests per second. You may receive 429 error responses if you exceed this limit.

Request Body

The request body is just an array of single-create JSON Request objects within an array with a key of "people", as seen below:

{
  "leads": [
    {
      "name": "My Lead",
      "email": {
          "email": "mylead@noemail.com",
          "category": "work"
      },
      "phone_numbers": [
          {
          "number": "415-123-45678",
          "category": "mobile"

          }
      ],
      "address": {
          "street": "123 Main Street",
          "city": "Savannah",
          "state": "Georgia",
          "postal_code": "31410",
          "country": "United States"
      },
      "custom_fields": [
          {
          "custom_field_definition_id": 100764,
          "value": "Text fields are 255 chars or less!"
          },
          {
          "custom_field_definition_id": 103481,
          "value": "Text area fields can have long text content"
          }
      ],
      "customer_source_id":331242
    }
  ]
}

Example Requests

Create New Person

Query200 Response

curl --location --request POST "https://api.copper.com/developer_api/v1/leads/bulk_create" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: " YOUR_EMAIL_HERE \
  --header "Content-Type: application/json" \
  --data '{
      "leads": [
          {
              "name": "Lead One"
          },
          {
              "name": "Lead Two"
          }
      ]
  }'

[
  {
    "id": 13244480,
    "name": "Lead One",
    "prefix": null,
    "first_name": "Lead",
    "last_name": "One",
    "middle_name": null,
    "suffix": null,
    "address": null,
    "assignee_id": null,
    "company_name": null,
    "customer_source_id": 331242,
    "details": null,
    "email": null,
    "interaction_count": 0,
    "monetary_value": null,
    "socials": [],
    "status": "New",
    "status_id": 208231,
    "tags": [],
    "title": null,
    "websites": [],
    "phone_numbers": [],
    "custom_fields": [],
    "date_created": 1502158444,
    "date_modified": 1502158444,
    "date_last_contacted": null
  },
  {
    "id": 13244481,
    "name": "Lead Two",
    "prefix": null,
    "first_name": "Lead",
    "last_name": "Two",
    "middle_name": null,
    "suffix": null,
    "address": null,
    "assignee_id": null,
    "company_name": null,
    "customer_source_id": 331242,
    "details": null,
    "email": null,
    "interaction_count": 0,
    "monetary_value": null,
    "socials": [],
    "status": "New",
    "status_id": 208231,
    "tags": [],
    "title": null,
    "websites": [],
    "phone_numbers": [],
    "custom_fields": [],
    "date_created": 1502158444,
    "date_modified": 1502158444,
    "date_last_contacted": null
  }
]