Batch update customers

Update customers in bulk
Written by Konstantine
Updated 1 month ago

You can update a number of customers at once with this method. If you want to update just one customer, it's better to use Update customer method.

➡️ Request

URL https://api.helpcrunch.com/v1/customers/batch
Method PUT
Headers Authorization: Bearer <your_api_key>

Read more about authorization header here.


Request Body Example

[
  {
    "customer": 542335,
    "name": "John Doe",
    "email": "[email protected]",
    "userId": "user_1234567890",
    "company": "Example Inc.",
    "phone": "+10233456781",
    "firstSeen": "1603885746",
    "lastSeen": "1603885746",
    "unsubscribed": false,
    "blocked": false,
    "source": "https://example.com",
    "referer": "https://example.com",
    "lastPage": "https://example.com",
    "locale": "uk",
    "createdFrom": "telegram",
    "integrationId": "465847687",
    "notes": "Lorem ipsum",
    "tags": [
      {
        "name": "vip",
        "color": "#ff0000"
      }
    ],
    "customData": [
      {
        "property": "subscription_status",
        "value": "active"
      },
      {
        "property": "number_of_payments",
        "value": 15
      },
      {
        "property": "last_paid_amount",
        "value": 15.99
      },
      {
        "property": "last_payment_date",
        "value": "1603885746"
      },
      {
        "property": "last_invoice_url",
        "value": "https://example.com/invoice.html"
      },
      {
        "property": "last_payment_was_successful",
        "value": true
      }
    ]
  }
]

Customer id is the identifier for the customer as given by HelpCrunch and is required for this method.


Limits

  • You should specify at least one customer in the request body.
  • Maximum number of customers you can add to the request body is 10. In order to update a bigger amount of customers - send a number of separate requests.
  • The overall requests limit is 120 per minute

Tips

  • All dates should be passed in the String (UNIX timestamp) format;
  • Locale filed should be passed as a string according to the ISO 639-1 standard;
  • Tag can be appended to the customer with Tag customer method or removed with Untag customer method. Tag will be automatically created and added to your account if you pass a non-existing one. You can assign any CSS color to the tag. If you don't specify it, the default #c377e0 color will be applied.
  • If you don't specify some fields in your request body, they will stay the same and will not be updated.
  • In order to clear the value of a specific field, you should pass a null value for it in your request body.
To create the new customData attribute, go to Settings → Contacts → Custom attributes and click 'Add new attribute'.


✅ Successful Response

If your request has succeeded, you'll get a 200 OK success status code together with the following response body. 

[
  {
    "id": 542335,
    "name": "John Doe",
    "email": "[email protected]",
    "userId": "user_1234567890",
    "company": "Example Inc.",
    "phone": "+10233456781",
    "firstSeen": "1603885746",
    "lastSeen": "1603885746",
    "location": {
      "regionCode": "Kyyivs'ka Oblast",
      "countryCode": "UA",
      "city": "Kyiv"
    },
    "device": {
      "id": 542335,
      "ip": "192.168.1.1",
      "timezone": "Europe/Kiev",
      "platform": "desktop",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36"
    },
    "unsubscribed": false,
    "blocked": false,
    "source": "https://example.com",
    "referer": "https://example.com",
    "lastPage": "https://example.com",
    "locale": "uk",
    "createdFrom": "telegram",
    "integrationId": "465847687",
    "notes": "Lorem ipsum",
    "tags": [
      {
        "name": "vip",
        "color": "#ff0000"
      }
    ],
    "customData": {
      "subscription_status": "active",
      "number_of_payments": 15,
      "last_paid_amount": 15.99,
      "last_payment_date": 1603885746,
      "last_invoice_url": "https://example.com/invoice.html",
      "last_payment_was_successful": true
    }
  }
]

You can get details on every Customer Object field in the Customer model article.

🛑 Error Responses

You may get one of the following error status codes and responses. More info on the errors is available here.

401 Unauthorized

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

404 Not Found

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "not_found",
      "message": "Chat not found"
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}

If you have any questions regarding the REST API, feel free to chat us any time.

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?