API for AI agents

Connect in three steps

1. In Crustomer, open Settings → API keys and click Create API key. Copy the key; it's shown once.
2. In your agent's custom connector, choose API key auth and paste the key. It's sent as a Bearer token.
3. Set the base address to https://crustomer.us/api/v1 and point it at this page or the OpenAPI file below.

Base address

https://crustomer.us/api/v1

Auth

Authorization: Bearer crsk_…

Format

JSON in and out, over HTTPS

OpenAPI

https://crustomer.us/api/v1/openapi.json

Limit

120 requests a minute per key

Add a lead

POST /v1/leads

curl https://crustomer.us/api/v1/leads \
  -H "Authorization: Bearer $CRUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_username": "mayatorres",
    "profile_url": "https://www.instagram.com/mayatorres/",
    "full_name": "Maya Torres",
    "bio": "Miami · house music · yoga teacher",
    "follower_count": 12400,
    "source_account": "reefrave",
    "vetted": false,
    "notes": "Posts about beach events every weekend."
  }'

A new lead comes back with 201 and { "data": { ...lead }, "created": true }. If the workspace already has that Instagram username, the lead is updated instead and comes back with 200 and "created": false: blanks are filled, the follower count and vetted are refreshed, and new notes are added once. The team's own name, bio and status are never overwritten.

To add up to 100 at once, send { "leads": [ {...}, {...} ] }. If any lead has a problem, nothing is saved and the error names it, like leads[3].instagram_username.

List leads

GET /v1/leads?limit=25

Newest first. limit is 1 to 100 (default 25). The response is { "data": [...], "next_cursor": "…" }; pass ?cursor= with that value for the next page. next_cursor is null on the last page. Filter with vetted=true or created_after=2026-09-01T00:00:00Z.

curl "https://crustomer.us/api/v1/leads?limit=50&vetted=true" \
  -H "Authorization: Bearer $CRUSTOMER_API_KEY"

Get one lead

GET /v1/leads/{id} returns { "data": { ...lead } }, or 404.

{
  "data": {
    "id": "5b0c7a4e-…",
    "instagram_username": "mayatorres",
    "profile_url": "https://www.instagram.com/mayatorres/",
    "full_name": "Maya Torres",
    "bio": "Miami · house music · yoga teacher",
    "follower_count": 12400,
    "source_account": "reefrave",
    "vetted": false,
    "notes": "Posts about beach events every weekend.",
    "status": "New",
    "category": "Unclear",
    "contact_type": "Attendee Lead",
    "source": "api",
    "created_at": "2026-09-29T15:04:05.000Z",
    "updated_at": "2026-09-29T15:04:05.000Z"
  }
}

Errors

Errors use normal HTTP status codes and one JSON shape:

{ "error": { "code": "validation_failed", "message": "Some fields need fixing. Nothing was saved.", "fields": { "follower_count": "Must be a whole number of followers, like 12400." } } }

Keys

• Each key belongs to one workspace and only sees that workspace's leads.
• Owners and admins make, rotate and turn off keys in Settings → API keys. Rotating makes a new key and turns the old one off at once.
• Crustomer only keeps a fingerprint of each key. If one is lost, rotate it.

Leads added through the API are for your team to review and reach out to by hand. Please only send what your agent may lawfully collect, and follow Instagram's rules on automated messaging.