Prospexly API

Authentication

Every request carries a key created in Settings. Keys are stored only as an Argon2id hash, so the value is shown once and cannot be recovered afterwards.

curl https://prospexly.com/api/v1/contacts?page_size=10 \
  -H "Authorization: Bearer pxly_YOUR_KEY"

Base URL https://prospexly.com/api/v1. An absent, malformed, revoked or expired key is a 401. A key that is valid but lacks the scope an endpoint needs is a 403, whatever your plan.

Scopes

Each key carries an explicit set of scopes chosen at creation. Grant the fewest that do the job — a key that only reads cannot be used to delete your pipeline.

Rate limits

Two limits apply. A burst limit of 500 requests a minute per key, and a daily limit set by your plan.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the last as a Unix timestamp in seconds. The daily window resets at midnight UTC. A refused request is not counted against you.

Paging and filtering

List endpoints return 25 rows by default and never more than 100. Asking for more is clamped rather than rejected, so a client that requests 5000 gets 100 and a truthful pagination block rather than an error it has to handle.

{
  "data": [ { "id": "...", "first_name": "Ada", "last_name": "Lovelace" } ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total": 118,
    "page_count": 5,
    "has_next": true,
    "has_previous": false
  }
}

Unrecognised sort, direction and filter values fall back to the default instead of erroring — a saved query should keep working after a column is renamed. Unknown fields in a request body are the opposite: they are rejected with a 400, because a typo there means you believe you set something you did not.

Endpoints

Creating and updating

A create returns 201 with the new record and a Location header. Records made through the API are marked with source api, so you can tell an integration’s rows from a manual entry inside the CRM.

curl -X POST https://prospexly.com/api/v1/contacts \
  -H "Authorization: Bearer pxly_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "role": "Head of Engineering"
  }'

A PATCH changes only the fields you send. There is no PUT: a full replace makes it far too easy to blank a field by omitting it.

curl -X PATCH https://prospexly.com/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer pxly_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "engaged"}'

Contacts carry first_name and last_name, never a combined name. There is no full-name field to write to, deliberately, and there will not be one.

AI lead search

The one asynchronous endpoint. A grounded search takes 10–60 seconds and longer when it retries, so it returns 202 with a status_url to poll rather than holding the connection open.

# Start the search. Returns 202 immediately.
curl -X POST https://prospexly.com/api/v1/lead-searches \
  -H "Authorization: Bearer pxly_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Dental practices",
    "country": "United Kingdom",
    "location": "Manchester",
    "max_results": 10
  }'

# Then poll until status is "completed" or "failed". A clean run takes about 40
# seconds; one that retries can take twice that.
curl https://prospexly.com/api/v1/lead-searches/SEARCH_ID \
  -H "Authorization: Bearer pxly_YOUR_KEY"

One company or one contact counts as one AI lead, so a search for ten companies can cost up to twenty. If your remaining allowance cannot cover the request it is trimmed to what it can, and clamped_from in the response reports what you originally asked for. An exhausted allowance is a 402, not a 429 — it will not clear on its own before the billing period does.

Errors

Every failure has the same shape, with a stable code to branch on and a message written to be read by a person.

{
  "error": {
    "code": "forbidden",
    "message": "This key does not have the `contacts.write` scope."
  }
}

A record belonging to another account is a 404 rather than a 403. That is not evasion: 403 would confirm the id exists, which is enough to enumerate other customers’ record ids one request at a time.