eva crm Public API

Contracts

Read contracts, follow them through their workflow, and attach files — the same way as leads.

A contract is the sale a lead became. The API reads them, moves them through their workflow and attaches files to them exactly as it does for leads. Creating or editing a contract is not available through the API, since that involves pricing and conversion that belong in the CRM.

GET List contracts

GET/v1/contracts

Contracts in your organisation, newest first, with the same cursor paging and guarantees as leads. Unknown parameters are a 422.

Query parameters
limitinteger · 1 to 100
Default: 50
cursorstring

From a previous nextCursor.

orderstring
Valid values: createdAt:desc, createdAt:asc, updatedAt:asc
Default: createdAt:desc
createdSincestring · date or date-time

In your timezone.

createdBeforestring · date or date-time

Exclusive.

updatedSincestring · date or date-time

Implies order=updatedAt:asc.

codestring · max 64

The CRM's contract number, such as CON000561.

referencestring · max 255

Exact match.

externalRefstring · max 255

Exact match.

leadIdstring · uuid

Contracts converted from that lead.

statusstring · list

One or several, comma-separated or repeated. All by default.

Valid values: open, on_hold, completed, cancelled
teststring
Valid values: exclude, include, only
Default: exclude
assignedTostring

A user's id or email, or none.

stagestring · list

A stage id or name, one or several. A name matches every contract workflow that has it — stage=Survey is the Survey stage of each one — unless workflow narrows it. Unknown names are a 422. See list workflows.

workflowstring · list

A workflow id or name, one or several.

daysInStagestring

Whole days in the current stage: 14 is at least 14, or eq:, gt:, gte:, lt:, lte: a number. As for leads.

Responses
200
A page of contracts, `hasMore` and `nextCursor`.
422
An unknown parameter, a value out of range, or a stale cursor. `fields` names it.
Example request
curl "https://api.evacrm.co.uk/v1/contracts?status=open&limit=50" \
  -H "Authorization: Bearer sk_..."
Example response · 200
{
  "object": "list",
  "data": [
    {
      "id": "6c99094a-…",
      "code": "CON000561",
      "reference": null,
      "leadReference": "web-form-8812",
      "externalRef": null,
      "source": null,
      "leadId": "1e4e3f90-…",
      "status": "open",
      "stage": { "id": "…", "name": "Survey booked", "category": "Live" },
      "workflow": { "id": "…", "name": "Contract Workflow Standard" },
      "stageChangedAt": "2026-09-02T11:14:03.512+01:00",
      "daysInStage": 2,
      "orderType": "Windows & Doors",
      "assigned": true,
      "assignee": { "id": "…", "name": "Tuan Dinh", "email": "…" },
      "assignedTeam": null,
      "test": false,
      "value": { "net": 4216.67, "vatRate": 20, "gross": 5060, "deposit": 1250, "depositPaid": true, "depositPaidAt": "…", "finance": false },
      "dates": {
        "contract": "…", "signed": "…", "survey": null,
        "provisionalInstallStart": null, "provisionalInstallEnd": null, "installStart": null, "installFinish": null,
        "installCompleted": false, "installCompletedAt": null, "warrantyStart": null, "warrantyEnd": null,
        "onHoldAt": null, "cancelledAt": null, "lastInvoiceAt": "…", "lastPaymentAt": "…"
      },
      "marketing": { "source": "Website", "campaign": null },
      "customer": { "id": "…", "code": "CUS007378", "firstName": "Jane", "lastName": "Smith", "fullName": "Jane Smith", "companyName": null, "consents": { "…": "…" } },
      "contact": { "id": "…", "email": "jane@example.com", "phoneNumber": null, "mobile": "07700900123" },
      "installAddress": { "address": "1 High Street", "address2": null, "address3": null, "town": "Reading", "county": null, "postcode": "RG1 1AA", "country": "United Kingdom", "contactName": null, "siteReference": null, "phone": null, "email": null },
      "createdAt": "…",
      "updatedAt": "…"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • status is derived the way the CRM does: cancelled wins, then on_hold, then completed (installation complete, or a stage in the Completed category), otherwise open.
  • value is the contract price. Unlike leads, prices are returned here, since integrators reconcile invoices against them.
  • installAddress is where the work happens, which need not be where the customer lives.

GET Get a contract

GET/v1/contracts/{id}

One contract, in the same shape.

Path parameters
idstring · uuidRequired

The contract's id.

Responses
200
The contract.
404
No such contract in your organisation.
Example request
curl https://api.evacrm.co.uk/v1/contracts/6c99094a-6f2e-4c7d-9b1e-2b4a8f3c1d05 \
  -H "Authorization: Bearer sk_..."
Example response · 200
{
  "id": "6c99094a-6f2e-4c7d-9b1e-2b4a8f3c1d05",
  "code": "CON000561",
  "reference": null,
  "leadReference": "web-form-8812",
  "externalRef": null,
  "source": null,
  "leadId": "1e4e3f90-…",
  "status": "open",
  "stage": {
    "id": "…",
    "name": "Survey booked",
    "category": "Live"
  },
  "workflow": {
    "id": "…",
    "name": "Contract Workflow Standard"
  },
  "stageChangedAt": "2026-09-02T11:14:03.512+01:00",
  "daysInStage": 2,
  "orderType": "Windows & Doors",
  "assigned": true,
  "assignee": {
    "id": "…",
    "name": "Tuan Dinh",
    "email": "tuan@example.com"
  },
  "assignedTeam": null,
  "test": false,
  "value": {
    "net": 4216.67,
    "vatRate": 20,
    "gross": 5060,
    "deposit": 1250,
    "depositPaid": true,
    "depositPaidAt": "2026-09-02T00:00:00.000+01:00",
    "finance": false
  },
  "dates": {
    "contract": "2026-09-01T00:00:00.000+01:00",
    "signed": "2026-09-01T00:00:00.000+01:00",
    "survey": null,
    "provisionalInstallStart": null,
    "provisionalInstallEnd": null,
    "installStart": null,
    "installFinish": null,
    "installCompleted": false,
    "installCompletedAt": null,
    "warrantyStart": null,
    "warrantyEnd": null,
    "onHoldAt": null,
    "cancelledAt": null,
    "lastInvoiceAt": "2026-09-02T10:14:03.512+01:00",
    "lastPaymentAt": "2026-09-02T10:14:03.512+01:00"
  },
  "marketing": {
    "source": "Website",
    "campaign": null
  },
  "customer": {
    "id": "…",
    "code": "CUS007378",
    "firstName": "Jane",
    "lastName": "Smith",
    "fullName": "Jane Smith",
    "companyName": null,
    "consents": {
      "doNotContact": false,
      "noMarketing": false,
      "marketingEmail": true,
      "marketingSms": false,
      "marketingPost": false
    }
  },
  "contact": {
    "id": "…",
    "email": "jane@example.com",
    "phoneNumber": null,
    "mobile": "07700900123"
  },
  "installAddress": {
    "address": "1 High Street",
    "address2": null,
    "address3": null,
    "town": "Reading",
    "county": null,
    "postcode": "RG1 1AA",
    "country": "United Kingdom",
    "contactName": null,
    "siteReference": null,
    "phone": null,
    "email": null
  },
  "createdAt": "2026-09-01T09:00:00.000+01:00",
  "updatedAt": "2026-09-02T10:14:03.512+01:00"
}

Stages

The contract's workflow, read and moved exactly as for leads: the workflow with allowedFromCurrent per stage, and a move by stage id or name that runs through the CRM with its actions. See lead stages for the shapes and rules.

GET/v1/contracts/{id}/stages
PUT/v1/contracts/{id}/stage

List workflows

GET/v1/contracts/workflows

Every contract workflow with its stages, in the shape of the lead version. The names and ids are what the stage and workflow filters on the list take; the same stage name usually exists in several workflows, and a filter by name covers all of them.

Notes and tasks

The notes written against a contract and the tasks raised on it, in the shapes and with the filters of lead notes and tasks. Read-only; both are written in the CRM. The response echoes the contract instead of the lead.

GET/v1/contracts/{id}/notes
GET/v1/contracts/{id}/tasks

Attachments

Files on a contract behave exactly as lead attachments, including documentType filing and the Photos default. Contract photos get the CRM's contract numbering.

GET/v1/contracts/{id}/attachments
POST/v1/contracts/{id}/attachments
DEL/v1/contracts/{id}/attachments/{fileId}
GET/v1/contracts/attachments/categories

Invoices, payments and appointments

A contract's ledger and its bookings have their own pages: invoices, payments and appointments.

Stages

See where a lead is in its workflow, and move it with the same rules the CRM applies.

Invoices

See a contract's invoices, payments, credit notes and refunds, and raise new invoices.

On this page

GET List contractsGET Get a contractStagesList workflowsNotes and tasksAttachmentsInvoices, payments and appointments