POST /api/v1/companies
Create or update up to 1,000 companies in a single request. Each row is matched and upserted by externalId; rows with no match are created.
Request
POST /api/v1/companies HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{
"companies": [
{
"name": "Acme Corp",
"domain": "acme.com",
"industry": "Retail",
"externalId": "SHOP-CO-1"
},
{
"name": "Globex",
"size": "51-200",
"website": "https://globex.example"
}
]
}The companies array must contain at least 1 item and at most 1,000.
Response — 200 (all rows succeeded)
When every row in the batch succeeds, the response status is 200:
{
"created": 1,
"updated": 1,
"errors": 0,
"results": [
{ "index": 0, "status": "created", "id": "cmq1abc2def3ghi4jkl5" },
{ "index": 1, "status": "updated", "id": "cmq6mno7pqr8stu9vwx0" }
]
}Each entry in results corresponds to the company at that position in your request array (zero-indexed).
Response — 207 Multi-Status (partial success)
When at least one row fails validation, the response status is 207. Failed rows appear in results with "status": "error":
{
"created": 1,
"updated": 0,
"errors": 1,
"results": [
{ "index": 0, "status": "created", "id": "cmq1abc2def3ghi4jkl5" },
{
"index": 1,
"status": "error",
"error": "name: Required"
}
]
}A row that fails validation does not abort the batch. Valid rows are written; failed rows are skipped and reported per-index in results.
Merge on update
When a row matches an existing company (by externalId), only the fields present in your request body are updated. Fields you omit retain their current values — this is a merge update, not a full replace.
For example, sending only { "externalId": "SHOP-CO-1", "industry": "E-commerce" } updates the industry without touching name, domain, notes, or any other field.
Quickstart
export AL_KEY="alk_live_xxx"
# Push your companies — run this on a schedule to keep them in sync
curl -s -X POST https://agentlyleads.com/api/v1/companies \
-H "Authorization: Bearer $AL_KEY" \
-H "Content-Type: application/json" \
-d '{
"companies": [
{
"name": "Acme Corp",
"domain": "acme.com",
"industry": "Retail",
"externalId": "SHOP-CO-1"
}
]
}'A typical integration is a nightly job in your CRM or e-commerce backend that reads its account/company list and POSTs it here. The first run creates everything; every later run updates by externalId.