Skip to content

Bulk Update Leads

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

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-update 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: 

1
2
3
{
  "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 updated successfully, it will be returned in the response array in the same JSON structure you would expect from the single-update endpoint.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "success": false,
  "message": {
    "name": [
      {
        "error": "invalid"
      }
    ]
  },
  "id": 12345
}

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-update JSON Request objects within an array (each with an ID added referencing a Lead that already exists) with a key of "leads", as seen below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "leads": [
    {
      "id": 123,
      "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

Update Leads

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
curl --location --request POST "https://api.copper.com/developer_api/v1/leads/bulk_update" \
  --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": [
          {
              "id": 12345,
              "name": "Lead One"
          },
          {
              "id": 67890,
              "name": "Lead Two"
          }
      ]
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
[
  {
    "id": 12345,
    "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": 67890,
    "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
  }
]