Leads

List leads

GET

/leads

One page of records, newest first unless you say otherwise, with the total count in meta so you know how far to paginate.

Required scope: leads:read.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Query Parameters

page?integer

1-based. meta.totalPages says how many there are.

Range1 <= value

Default1

per_page?integer

Rows per page. A value above 200 returns 400 - never a silent clamp.

Range1 <= value <= 200

Default50

sort?string

Prefix with - for descending. An undeclared sort returns 400.

Default"-createdAt"

Value in"createdAt""-createdAt""lastContactedAt""-lastContactedAt""companyName""-companyName"

q?string

Case-insensitive "contains", across: companyName, contactName, email.

filter[status]?string

Exact match on status.

Value in"to_contact""contacted""following_up""qualified""converted""disqualified"

filter[clientId]?string

Exact match on clientId.

Response Body

The requested page.

application/json

response

data*array<>

meta*

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads'

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads'

Example ResponseSchema

{
  "data": [
    {
      "id": "string",
      "clientId": "string",
      "companyName": "string",
      "contactName": "string",
      "email": "string",
      "phone": "string",
      "website": "string",
      "status": "to_contact",
      "notes": "string",
      "lastContactedAt": "2019-08-24T14:15:22Z",
      "convertedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "customFields": {}
    }
  ],
  "meta": {
    "page": 0,
    "perPage": 0,
    "total": 0,
    "totalPages": 0
  }
}

{  "data": [    {      "id": "string",      "clientId": "string",      "companyName": "string",      "contactName": "string",      "email": "string",      "phone": "string",      "website": "string",      "status": "to_contact",      "notes": "string",      "lastContactedAt": "2019-08-24T14:15:22Z",      "convertedAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "customFields": {}    }  ],  "meta": {    "page": 0,    "perPage": 0,    "total": 0,    "totalPages": 0  }}

Links are given as the target's public id (clientId: "hsbftmp3f5"); the API resolves them server-side. Fields the database requires but the interface decides for you are filled in the same way here.

Required scope: leads:write.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Header Parameters

Request Body

application/json

body

companyName?|null

contactName?|null

email?|null

phone?|

Phone number, stored in E.164 (+33612345678). A national number is read as French; a number that is not valid for its country is refused (validation_failed).

website?|null

sourceId?string|null

status?string

Value in"to_contact""contacted""following_up""qualified""converted""disqualified"

notes?string|null

lastContactedAt?string|null

clientId?string|null

customFields?

createdAt?string

When this actually happened, for an import. Past dates only; defaults to now. updatedAt follows it unless the body sets one.

Formatdate-time

Response Body

Created. The body is the new record, as a read would return it.

application/json

response

data*

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "data": {
    "id": "string",
    "clientId": "string",
    "companyName": "string",
    "contactName": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "status": "to_contact",
    "notes": "string",
    "lastContactedAt": "2019-08-24T14:15:22Z",
    "convertedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "customFields": {}
  }
}

{  "data": {    "id": "string",    "clientId": "string",    "companyName": "string",    "contactName": "string",    "email": "string",    "phone": "string",    "website": "string",    "status": "to_contact",    "notes": "string",    "lastContactedAt": "2019-08-24T14:15:22Z",    "convertedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "customFields": {}  }}

Retrieve a lead

GET

/leads/{id}

The full record, custom fields included when the resource carries them. A record from another agency is a 404, not a 403 - its existence is not ours to confirm.

Required scope: leads:read.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Path Parameters

id*string

The record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.

Response Body

Found.

application/json

response

data*

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads/string'

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads/string'

Example ResponseSchema

{
  "data": {
    "id": "string",
    "clientId": "string",
    "companyName": "string",
    "contactName": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "status": "to_contact",
    "notes": "string",
    "lastContactedAt": "2019-08-24T14:15:22Z",
    "convertedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "customFields": {}
  }
}

{  "data": {    "id": "string",    "clientId": "string",    "companyName": "string",    "contactName": "string",    "email": "string",    "phone": "string",    "website": "string",    "status": "to_contact",    "notes": "string",    "lastContactedAt": "2019-08-24T14:15:22Z",    "convertedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "customFields": {}  }}

Update a lead

PATCH

/leads/{id}

A partial update: only the fields you send change. One exception - customFields is replaced wholesale, not merged, so sending it with a single key clears the others. Read the record, merge, then write.

Required scope: leads:write.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Path Parameters

id*string

The record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.

Request Body

application/json

body

companyName?|null

contactName?|null

email?|null

phone?|

Phone number, stored in E.164 (+33612345678). A national number is read as French; a number that is not valid for its country is refused (validation_failed).

website?|null

sourceId?string|null

status?string

Value in"to_contact""contacted""following_up""qualified""converted""disqualified"

notes?string|null

lastContactedAt?string|null

clientId?string|null

customFields?

Response Body

Updated. The body is the record as it now stands.

application/json

response

data*

Example Request

curl -X PATCH 'https://api.usedashly.com/v1/leads/string' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X PATCH 'https://api.usedashly.com/v1/leads/string' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "data": {
    "id": "string",
    "clientId": "string",
    "companyName": "string",
    "contactName": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "status": "to_contact",
    "notes": "string",
    "lastContactedAt": "2019-08-24T14:15:22Z",
    "convertedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "customFields": {}
  }
}

{  "data": {    "id": "string",    "clientId": "string",    "companyName": "string",    "contactName": "string",    "email": "string",    "phone": "string",    "website": "string",    "status": "to_contact",    "notes": "string",    "lastContactedAt": "2019-08-24T14:15:22Z",    "convertedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "customFields": {}  }}

Delete a lead

DELETE

/leads/{id}

Permanent. The audit log keeps the trace; the record does not come back.

Required scope: leads:write.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Path Parameters

id*string

The record's public id (hsbftmp3f5), as returned in the id field. An internal UUID returns 404.

Response Body

Deleted. Empty body.

Example Request

curl -X DELETE 'https://api.usedashly.com/v1/leads/string'

Example Request

curl -X DELETE 'https://api.usedashly.com/v1/leads/string'

Example Response

Empty

List available actions

GET

/leads/actions

Every verb this resource answers to, with its target and the JSON Schema of its body - the same contracts this document describes, readable at runtime.

Required scope: leads:read.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Response Body

The available verbs.

application/json

response

data*array<>

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads/actions'

Example Request

curl -X GET 'https://api.usedashly.com/v1/leads/actions'

Example ResponseSchema

{
  "data": [
    {
      "name": "string",
      "label": "string",
      "description": "string",
      "target": "item",
      "readOnly": true,
      "path": "string",
      "input": {}
    }
  ]
}

{  "data": [    {      "name": "string",      "label": "string",      "description": "string",      "target": "item",      "readOnly": true,      "path": "string",      "input": {}    }  ]}

Convert to a deal

POST

/leads/{id}/actions/convert

Turns the lead into a deal: the organisation and the contact are linked or created, the deal lands on the stage you choose (or the first one), and the lead is marked converted with a pointer to the deal.

Does what the dashboard's convertLeadAction does - same implementation, so the two cannot diverge.

Required scope: leads:write.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

Path Parameters

id*string

The public id of the record to act on. It is resolved inside your agency before the action runs, so an id from another tenant is a 404 and never reaches it.

Header Parameters

Request Body

application/json

body

dealName?string

Lengthlength <= 200

stageId?string

Lengthlength <= 60

Response Body

Done.

application/json

response

data*unknown

The action's result; its shape depends on the verb.

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads/string/actions/convert' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads/string/actions/convert' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "data": null
}

{  "data": null}

Change the owner

POST

/leads/{id}/actions/set-owner

Hands the lead to an agency member (see /v1/members), or clears its owner with ownerId: null.

Does what the dashboard's setLeadOwnerAction does - same implementation, so the two cannot diverge.

Required scope: leads:write.

Authorization

bearerAuth

headerAuthorizationBearer <token>

Your agency's API key: Authorization: Bearer ak_…. Created in Connectors → API & webhooks and shown once. A key authenticates an agency, not a person.

body

ownerId?|null

Response Body

Done.

application/json

response

data*unknown

The action's result; its shape depends on the verb.

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads/string/actions/set-owner' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://api.usedashly.com/v1/leads/string/actions/set-owner' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "data": null
}

{  "data": null}

List leadsCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Create a leadCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Retrieve a leadCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Update a leadCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Delete a leadCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

List available actionsCopy Anchor Link

AuthorizationCopy Anchor Link

Response BodyCopy Anchor Link

Convert to a dealCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Change the ownerCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

List leads

Authorization

Query Parameters

Response Body

Create a lead

Authorization

Header Parameters

Request Body

Response Body

Retrieve a lead

Authorization

Path Parameters

Response Body

Update a lead

Authorization

Path Parameters

Request Body

Response Body

Delete a lead

Authorization

Path Parameters

Response Body

List available actions

Authorization

Response Body

Convert to a deal

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

Change the owner

Authorization

Path Parameters

Header Parameters

Request Body

Response Body