API Reference

SurelyCrm exposes a set of JSON endpoints for programmatic integration. Use these APIs to create customers, search records, manage workflows, and interact with the telephony system from your own applications.

Authentication Required: Most endpoints require an active session cookie (standard browser login). Endpoints under /Api/ use API key authentication. Administrative endpoints require the Administrator role.

Command Line Tool: You can also interact with these endpoints using the SurelyCrm CLI. Install it with npm install -g @surelycrm/cli.

Authentication

API Key Authentication

Endpoints under /Api/ accept a GUID API key passed in the request header:

apiKey: {your-guid-api-key}

Administrators can view or regenerate the API key in Settings > Application Settings. Keep this key secure — treat it like a password. If compromised, regenerate it immediately.

Session Authentication

All other endpoints use standard ASP.NET Core cookie authentication. Log in via the web interface and use the resulting session cookie for subsequent API requests.

Customers API

Create Customer

Creates a new customer record in the system.

Property	Value
Endpoint	`POST /Api/Create`
Authentication	API Key (`apiKey` header)
Content-Type	`application/json`

Required fields: Only title, firstname, surname and referenceNumber are required. All other fields are optional.

Request Body

{
  "title": "Mr",
  "firstname": "John",
  "surname": "Davies",
  "referenceNumber": "optional-override",
  "address1": "123 High Street",
  "address2": "",
  "address3": "",
  "address4": "",
  "town": "Manchester",
  "city": "Greater Manchester",
  "postcode": "M1 1AA",
  "homePhone": "01611234567",
  "mobilePhone": "07700900123",
  "emailAddress": "john.davies@example.com",
  "notificationsEnabled": true,
  "importantDate": "2025-06-15T00:00:00",
  "dateOfBirth": "1985-03-20T00:00:00",
  "website": "https://example.com",
  "statusId": "00000000-0000-0000-0000-000000000000",
  "ownerId": "00000000-0000-0000-0000-000000000000",
  "referredBy": "Google Ads",
  "customFields": {
    "ContractType": "Premium",
    "Priority": "High"
  }
}

Field Reference

Field	Type	Required	Description
`title`	string	Yes	Mr, Mrs, Miss, or Ms
`firstname`	string	Yes	First name
`surname`	string	Yes	Surname
`referenceNumber`	string	Yes	Customer reference number
`address1`	string	No	First line of address
`address2`	string	No	Second line of address
`address3`	string	No	Third line of address
`address4`	string	No	Fourth line of address
`town`	string	No	Town
`city`	string	No	City
`postcode`	string	No	Postcode
`homePhone`	string	No	Home telephone number
`mobilePhone`	string	No	Mobile telephone number
`emailAddress`	string	No	Email address
`notificationsEnabled`	boolean	No	Consent to marketing communications
`importantDate`	datetime	No	Key date for the customer
`dateOfBirth`	datetime	No	Date of birth
`website`	string	No	Website URL
`statusId`	guid	No	Status GUID. Omit for default.
`ownerId`	guid	No	Assigned user GUID. Omit for unassigned.
`referredBy`	string	No	Referral source
`customFields`	object	No	Key-value pairs of custom field data

Response

200 OK — Customer created successfully. Returns the new customer's GUID:

"550e8400-e29b-41d4-a716-446655440000"

400 Bad Request — Validation failed or customer could not be created. Returns error details:

{
  "Title": ["The Title field is required."],
  "Firstname": ["The Firstname field is required."],
  "Surname": ["The Surname field is required."],
  "ReferenceNumber": ["The ReferenceNumber field is required."]
}

401 Unauthorized — Missing or invalid API key.

Get Customer by GUID

Retrieves a single customer record by its unique identifier.

Property	Value
Endpoint	`GET /Api/customer/{id}`
Authentication	API Key (`apiKey` header)

Response

200 OK — Returns the customer record:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "referenceNumber": "1234567890",
  "title": "Mr",
  "firstname": "John",
  "surname": "Davies",
  "address1": "123 High Street",
  "address2": "",
  "address3": "",
  "address4": "",
  "town": "Manchester",
  "city": "Greater Manchester",
  "postcode": "M1 1AA",
  "homePhone": "01611234567",
  "mobilePhone": "07700900123",
  "emailAddress": "john.davies@example.com",
  "notificationsEnabled": true,
  "importantDate": "2025-06-15T00:00:00",
  "dateOfBirth": "1985-03-20T00:00:00",
  "website": "https://example.com",
  "age": 40,
  "statusId": "00000000-0000-0000-0000-000000000000",
  "ownerId": "00000000-0000-0000-0000-000000000000",
  "referredBy": "Google Ads",
  "customFields": {
    "ContractType": "Premium",
    "Priority": "High"
  }
}

401 Unauthorized — Missing or invalid API key.

404 Not Found — Customer with the specified GUID does not exist.

Get Customer by Reference Number

Retrieves a single customer record by its reference number.

Property	Value
Endpoint	`GET /Api/customer/reference/{referenceNumber}`
Authentication	API Key (`apiKey` header)

Response

200 OK — Returns the customer record (same shape as Get Customer by GUID).

400 Bad Request — Reference number is missing.

401 Unauthorized — Missing or invalid API key.

404 Not Found — Customer with the specified reference number does not exist.

Get Customer by Email Address

Retrieves a single customer record by email address.

Property	Value
Endpoint	`GET /Api/customer/byEmail/{emailAddress}`
Authentication	API Key (`apiKey` header)

Response

200 OK — Returns the customer record (same shape as Get Customer by GUID).

400 Bad Request — Email address is missing.

401 Unauthorized — Missing or invalid API key.

404 Not Found — Customer with the specified email address does not exist.

Update Customer

Updates an existing customer record. The customer ID in the request body must match the ID in the route.

Property	Value
Endpoint	`PUT /Api/customer/{id}`
Authentication	API Key (`apiKey` header)
Content-Type	`application/json`

Required fields: Only title, firstname, surname and referenceNumber are required. All other fields are optional.

Request Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Mr",
  "firstname": "John",
  "surname": "Davies",
  "referenceNumber": "1234567890",
  "address1": "123 High Street",
  "address2": "",
  "address3": "",
  "address4": "",
  "town": "Manchester",
  "city": "Greater Manchester",
  "postcode": "M1 1AA",
  "homePhone": "01611234567",
  "mobilePhone": "07700900123",
  "emailAddress": "john.davies@example.com",
  "notificationsEnabled": true,
  "importantDate": "2025-06-15T00:00:00",
  "dateOfBirth": "1985-03-20T00:00:00",
  "website": "https://example.com",
  "statusId": "00000000-0000-0000-0000-000000000000",
  "ownerId": "00000000-0000-0000-0000-000000000000",
  "referredBy": "Google Ads",
  "customFields": {
    "ContractType": "Premium",
    "Priority": "High"
  }
}

Response

200 OK — Customer updated successfully.

400 Bad Request — Validation failed, IDs do not match, or update could not be completed.

401 Unauthorized — Missing or invalid API key.

404 Not Found — Customer with the specified GUID does not exist.

Change Account Status

Changes the status of a customer account.

Property	Value
Endpoint	`POST /Api/customer/{customerId}/status`
Authentication	API Key (`apiKey` header)
Content-Type	`application/json`

Request Body

{
  "statusId": "550e8400-e29b-41d4-a716-446655440000"
}

Response

200 OK — Returns true when the status was changed successfully.

400 Bad Request — Invalid request or status could not be changed.

401 Unauthorized — Missing or invalid API key.

404 Not Found — Customer or status record not found.

Start Workflow for Customer

Starts a workflow instance for a customer. Provide either the workflow GUID or the workflow name; one is required.

Property	Value
Endpoint	`POST /Api/customer/{customerId}/workflow`
Authentication	API Key (`apiKey` header)
Content-Type	`application/json`

Request Body

{
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowName": "Welcome Sequence",
  "contextData": "{}"
}

Field Reference

Field	Type	Required	Description
`workflowId`	guid	One of `workflowId` or `workflowName`	GUID of the active workflow to start
`workflowName`	string	One of `workflowId` or `workflowName`	Name of the active workflow to start
`contextData`	string	No	JSON context data for the workflow instance. Defaults to `"{}"`.

Response

200 OK — Workflow started successfully:

{
  "success": true,
  "instanceId": "550e8400-e29b-41d4-a716-446655440001"
}

400 Bad Request — Neither workflow ID nor name was provided, the workflow is not active, or the workflow could not be started.

Get Support Ticket by Id

Retrieves a single support ticket, including its messages.

Property	Value
Endpoint	`GET /Api/support/tickets/{id}`
Authentication	API Key (`apiKey` header)

Response

200 OK — Returns the support ticket record with messages:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "customerName": "John Davies",
  "customerEmail": "john@example.com",
  "subject": "Login issue",
  "referenceNumber": "SR-001",
  "status": "Open",
  "priority": "Normal",
  "categoryName": "Technical Support",
  "assignedToName": "Jane Smith",
  "messageCount": 3,
  "unreadMessageCount": 1,
  "lastMessageDate": "2025-06-15T14:30:00",
  "createDate": "2025-06-15T10:00:00",
  "messages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "supportRequestId": "550e8400-e29b-41d4-a716-446655440000",
      "message": "I cannot log in.",
      "isFromCustomer": true,
      "isInternal": false,
      "sentByName": "John Davies",
      "readAt": null,
      "createDate": "2025-06-15T10:00:00"
    }
  ]
}

401 Unauthorized — Missing or invalid API key.

404 Not Found — Support ticket not found.

Get Support Tickets

Returns support tickets. Use global list filters (newTickets or recentlyReplied) for open/recently-active tickets, or customer filters (customerId or customerEmailAddress) to list all tickets for a specific customer. Customer filters and list filters are mutually exclusive.

Property	Value
Endpoint	`GET /Api/support/tickets`
Authentication	API Key (`apiKey` header)

Query Parameters

Parameter	Type	Required	Description
`newTickets`	boolean	One mode selector only	Return open tickets ordered by creation date
`recentlyReplied`	boolean	One mode selector only	Return tickets with messages in the recent period
`customerId`	guid	One mode selector only	Return all tickets for the customer with this GUID
`customerEmailAddress`	string	One mode selector only	Return all tickets for the customer with this email address
`hours`	integer	No	Number of hours to look back when `recentlyReplied` is true. Defaults to `24`.
`page`	integer	No	Page number. Defaults to `1`.
`pageSize`	integer	No	Page size. Defaults to `25`.

Response

200 OK — Returns an array of support ticket records:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "550e8400-e29b-41d4-a716-446655440001",
    "customerName": "John Davies",
    "customerEmail": "john@example.com",
    "subject": "Login issue",
    "referenceNumber": "SR-001",
    "status": "Open",
    "priority": "Normal",
    "categoryName": "Technical Support",
    "assignedToName": "Jane Smith",
    "messageCount": 3,
    "unreadMessageCount": 1,
    "lastMessageDate": "2025-06-15T14:30:00",
    "createDate": "2025-06-15T10:00:00"
  }
]

400 Bad Request — Missing selector, conflicting filters, or customer not found.

401 Unauthorized — Missing or invalid API key.

Reply to Support Ticket

Adds a staff reply to an existing support ticket. Optionally closes the ticket after the reply.

Property	Value
Endpoint	`POST /Api/support/tickets/{id}/reply`
Authentication	API Key (`apiKey` header)
Content-Type	`application/json`

Request Body

{
  "message": "Thanks for getting in touch. We are looking into this now.",
  "isInternal": false,
  "closeAfterReply": false
}

Field Reference

Field	Type	Required	Description
`message`	string	Yes	The reply text
`isInternal`	boolean	No	Whether the reply is internal-only. Defaults to `false`.
`closeAfterReply`	boolean	No	Close the ticket after posting the reply. Defaults to `false`.

Response

200 OK — Reply posted successfully:

{
  "success": true
}

400 Bad Request — Missing message or reply could not be posted.

401 Unauthorized — Missing or invalid API key.

404 Not Found — Support ticket not found.

Get Customers by Age

Returns all customers whose age matches the supplied comparison.

Property	Value
Endpoint	`GET /Api/customers/byAge?age={age}&comparison={comparison}`
Authentication	API Key (`apiKey` header)

Query Parameters

Parameter	Type	Required	Description
`age`	integer	Yes	The age value to compare against
`comparison`	string	No	One of `equal`, `greater`, `less`, `greaterthanorequal`, or `lessthanorequal`. Defaults to `equal`.

Response

200 OK — Returns an array of matching customer records:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "referenceNumber": "1234567890",
    "title": "Mr",
    "firstname": "John",
    "surname": "Davies",
    "age": 40,
    "emailAddress": "john.davies@example.com",
    "statusId": "00000000-0000-0000-0000-000000000000"
  }
]

400 Bad Request — Invalid comparison value supplied.

401 Unauthorized — Missing or invalid API key.

Search Customer by Phone

Searches for customers by phone number across mobile and home phone fields. Automatically handles UK format variations.

Property	Value
Endpoint	`GET /Customer/SearchByPhone?phoneNumber={number}`
Authentication	Session cookie

Response

{
  "success": true,
  "customers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "referenceNumber": "1234567890",
      "title": "Mr",
      "firstname": "John",
      "surname": "Davies",
      "dateOfBirth": "20/03/1985",
      "address": "123 High Street, Manchester, M1 1AA",
      "mobilePhone": "07700900123",
      "homePhone": "01611234567",
      "status": "Active"
    }
  ]
}

Telephony API

Generate Twilio Token

Generates a Twilio access token for the authenticated agent to use the embedded dialer.

Property	Value
Endpoint	`GET /TwilioToken/Generate` or `POST /TwilioToken/Generate`
Authentication	Session cookie

Response

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Change Agent Status

Updates the agent's availability status in the call queue.

Property	Value
Endpoint	`GET /TwilioAgent/ChangeStatus?status={Ready\|Busy}`
Authentication	Session cookie

Workflow API

Save Workflow

Creates or updates a workflow definition.

Property	Value
Endpoint	`POST /Workflow/SaveWorkflow`
Authentication	Session cookie (Admin)
Content-Type	`application/json`

Request Body

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Welcome Sequence",
  "description": "Send welcome email and SMS to new leads",
  "isActive": true,
  "stages": [
    {
      "name": "Send Welcome Email",
      "actionType": "Email",
      "actionConfiguration": "{\"templateId\":\"guid-here\"}",
      "waitDuration": "00:00:00",
      "sortOrder": 1
    }
  ]
}

Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Activate / Deactivate Workflow

POST /Workflow/ActivateWorkflow?id={workflowId}
POST /Workflow/DeactivateWorkflow?id={workflowId}

Both return { "success": true } on success.

Delete Workflow

DELETE /Workflow/DeleteWorkflow?id={workflowId}

Start Workflow Instance

POST /Workflow/StartWorkflow

Body:
{
  "workflowId": "guid",
  "customerId": "guid"
}

Returns { "success": true, "instanceId": "guid" }.

Control Instance

POST /Workflow/PauseInstance?id={instanceId}
POST /Workflow/ResumeInstance?id={instanceId}
POST /Workflow/CancelInstance?id={instanceId}
POST /Workflow/AdvanceInstance?id={instanceId}

All return { "success": true } on success.

Bulk Action API

Preview Bulk Action

These authenticated Administrator controller endpoints are used by the Bulk Actions page. They are not part of the external /Api contract. The existing Customer behaviour remains available, and Lead support uses the same endpoints whenever the Leads feature is enabled.

For a Lead preview, set recordType to Lead and use a saved Lead view or a manual search with an optional Campaign filter. Converted Leads are excluded.

POST /BulkAction/Preview

Body:
{
  "recordType": "Customer",
  "statusFilterOperator": "In",
  "statusIds": ["guid-1", "guid-2"],
  "ownerIds": ["guid-3"],
  "importantDateFrom": "2025-01-01",
  "importantDateTo": "2025-12-31",
  "balanceFrom": 0,
  "balanceTo": 1000,
  "notificationsEnabledOnly": true
}

Response

{
  "success": true,
  "data": {
    "recordType": "Customer",
    "totalRecordsMatched": 245,
    "sampleCustomers": [ /* first 10 matches */ ]
  }
}

A Lead response uses recordType: Lead, totalRecordsMatched, and sampleLeads. The Lead sample is bounded to 10 records.

Create Bulk Action Job

POST /BulkAction/CreateJob

Body:
{
  "actionRequest": {
    "recordType": "Lead",
    "actionType": "Email",
    "useTemplate": true,
    "emailTemplateId": "guid",
    "filter": {
      "recordType": "Lead",
      "sourceType": "LeadView",
      "leadViewId": "guid"
    }
  }
}

Lead jobs support Email, Sms, SetStatus, and StartWorkflow. Supply subject/content or the relevant template ID for communication actions, statusId for SetStatus, and workflowId for StartWorkflow. Lead status and workflow IDs must belong to the Lead record type. A manual Lead filter uses sourceType: ManualFilter, searchTerm, and optional campaignId.

Manage Jobs

GET    /BulkAction/GetJobs
GET    /BulkAction/GetJob?id={jobId}
POST   /BulkAction/PauseJob?id={jobId}
POST   /BulkAction/ResumeJob?id={jobId}
POST   /BulkAction/CancelJob?id={jobId}
POST   /BulkAction/DeleteJob?id={jobId}
POST   /BulkAction/RetryJob?id={jobId}

Support API

List Support Requests

GET /support?status={status}&assignedTo={userId}

Returns HTML view. For JSON data, use the existing authenticated session.

Create Support Request

POST /support/new

Body (form data):
- customerId
- categoryId
- subject
- message
- priority (Low, Normal, High, Urgent)

Reply to Request

POST /support/{id}/reply

Body (form data):
- message
- isInternal (boolean)
- closeAfterReply (boolean)

Update Status / Assign / Close

POST /support/{id}/status   (form: status)
POST /support/{id}/assign   (form: userId)
POST /support/{id}/close

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
400 Bad Request	Validation failed or malformed request
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Authenticated but insufficient permissions
404 Not Found	Resource does not exist
409 Conflict	Request conflicts with existing data
422 Unprocessable Entity	Selection is valid but unavailable
500 Internal Server Error	Unexpected server error

cURL Examples

Create Customer

curl -X POST https://app.surelycrm.co.uk/Api/Create \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "title": "Mr",
    "firstname": "John",
    "surname": "Davies",
    "address1": "123 High Street",
    "town": "Manchester",
    "city": "Greater Manchester",
    "postcode": "M1 1AA",
    "emailAddress": "john@example.com",
    "notificationsEnabled": true,
    "mobilePhone": "07700900123"
  }'

Search by Phone

curl -X GET "https://app.surelycrm.co.uk/Customer/SearchByPhone?phoneNumber=07700900123" \
  -H "Cookie: .AspNetCore.Cookies={your-session-cookie}"

Start Workflow

curl -X POST https://app.surelycrm.co.uk/Workflow/StartWorkflow \
  -H "Content-Type: application/json" \
  -H "Cookie: .AspNetCore.Cookies={your-session-cookie}" \
  -d '{
    "workflowId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "550e8400-e29b-41d4-a716-446655440001"
  }'

Get Customer by GUID

curl -X GET "https://app.surelycrm.co.uk/Api/customer/550e8400-e29b-41d4-a716-446655440000" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Customer by Reference Number

curl -X GET "https://app.surelycrm.co.uk/Api/customer/reference/1234567890" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Update Customer

curl -X PUT "https://app.surelycrm.co.uk/Api/customer/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Mr",
    "firstname": "John",
    "surname": "Davies",
    "address1": "123 High Street",
    "town": "Manchester",
    "city": "Greater Manchester",
    "postcode": "M1 1AA",
    "emailAddress": "john@example.com",
    "notificationsEnabled": true,
    "mobilePhone": "07700900123"
  }'

Start Workflow for Customer

curl -X POST "https://app.surelycrm.co.uk/Api/customer/550e8400-e29b-41d4-a716-446655440000/workflow" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "workflowName": "Welcome Sequence",
    "contextData": "{}"
  }'

Get Customers by Age

curl -X GET "https://app.surelycrm.co.uk/Api/customers/byAge?age=30&comparison=greater" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Support Ticket by Id

curl -X GET "https://app.surelycrm.co.uk/Api/support/tickets/550e8400-e29b-41d4-a716-446655440000" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Support Tickets for Customer

# By customer id
curl -X GET "https://app.surelycrm.co.uk/Api/support/tickets?customerId=550e8400-e29b-41d4-a716-446655440001" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

# By customer email
curl -X GET "https://app.surelycrm.co.uk/Api/support/tickets?customerEmailAddress=john@example.com" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get New Support Tickets

curl -X GET "https://app.surelycrm.co.uk/Api/support/tickets?newTickets=true&page=1&pageSize=25" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Opportunities API

Manage the sales pipeline. Opportunities are linked to leads and track deal value, stage, probability, and expected close date.

List Opportunities

curl -X GET "https://app.surelycrm.co.uk/Api/opportunities?search=&leadId=&stage=&status=&page=1" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Opportunity by Id

curl -X GET "https://app.surelycrm.co.uk/Api/opportunities/550e8400-e29b-41d4-a716-446655440000" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Opportunities for Lead

curl -X GET "https://app.surelycrm.co.uk/Api/leads/550e8400-e29b-41d4-a716-446655440000/opportunities" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Create Opportunity

curl -X POST "https://app.surelycrm.co.uk/Api/opportunities" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Website redesign project",
    "description": "Full redesign of company website",
    "value": 5000.00,
    "currency": "GBP",
    "probability": 50,
    "stage": "Prospecting",
    "status": "Open",
    "expectedCloseDate": "2026-12-31"
  }'

Update Opportunity

curl -X PUT "https://app.surelycrm.co.uk/Api/opportunities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Website redesign project",
    "value": 7500.00,
    "probability": 75,
    "stage": "Proposal",
    "status": "Open"
  }'

Change Opportunity Stage

curl -X POST "https://app.surelycrm.co.uk/Api/opportunities/550e8400-e29b-41d4-a716-446655440000/stage" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "stage": "ClosedWon",
    "notes": "Verbal agreement received"
  }'

External Campaign Selection API

The reference contract is available only when the ReferenceBackedCampaignPromotion feature is enabled for the current tenant. References are opaque and tenant-scoped; do not infer meaning from them. A campaign's referenceCode is its CRM display/search code, not its external identity.

List Active Campaign Locations

GET /Api/external/campaign-locations

Returns active locations only. Each item contains externalReference, name, and description.

Look Up an Active Location

GET /Api/external/campaign-locations/{externalReference}

Returns 404 when the reference is unknown, inactive, belongs to another tenant, or the feature is disabled.

List Eligible Campaigns

GET /Api/external/campaigns?locationReference={locationExternalReference}

Returns campaigns for the active location that are New or InProgress. Finished campaigns are not returned.

Create or Reconcile a Campaign

POST /Api/external/campaigns
{
  "externalReference": "dark-campaign-100",
  "name": "Autumn outreach",
  "referenceCode": "AUT-2026-001",
  "locationExternalReference": "loc_opaque_reference"
}

A first request returns 201; an identical retry returns 200 and the same campaign. A reused external reference with a changed name, display reference code, or location returns 409. An unknown or inactive location returns 422. Do not substitute referenceCode for externalReference.

External Promotion API

The same feature enables an atomic, reference-only handoff from Dark Leads. It is the only contract Dark Leads uses: it neither receives CRM UUIDs nor uses legacy UUID-based Lead or Opportunity endpoints.

Create or Reconcile a Lead and Initial Opportunity

POST /Api/external/promotions
{
  "locationExternalReference": "loc_opaque_reference",
  "campaignExternalReference": "dark-campaign-100",
  "leadExternalReference": "dark-handoff-100",
  "businessName": "Example Business",
  "contactPerson": "Business contact",
  "contactEmail": "contact@example.test",
  "websiteUrl": "https://example.test",
  "salesBrief": "Sales-ready snapshot..."
}

Each reference is required, is 1 to 64 characters, starts with an ASCII letter or digit, and then contains only ASCII letters, digits, underscores, or hyphens. businessName is required and is at most 200 characters. Contact fields are optional. The optional salesBrief is plain text or simple Markdown treated as untrusted text, at most 8,000 characters, trimmed with blank values stored as null.

Surely locks and verifies the location and campaign, then creates the Lead, its initial Prospecting/Open Opportunity, and activity history in one database transaction. The location must be active, the campaign must belong to it, and the campaign must be New or InProgress. The Opportunity title is the business name; its value is 0 GBP, with no owner, probability, or date.

Retries and conflicts

The supplied leadExternalReference is the handoff key. Strings are trimmed; blank optional contact fields become null. References and email are compared case-insensitively. Other fields are compared after trimming with their exact case.

While the selected location remains active and the campaign remains eligible, an identical canonical retry returns 200 with both leadCreated and opportunityCreated set to false. A changed canonical payload returns 409 with only the differing field names. A location/campaign mismatch or an incomplete existing pair also returns 409; it exposes no internal IDs or field values. Do not retry with a different payload or fall back to a UUID endpoint.

The salesBrief is a creation-time snapshot: it is stored only when the Lead is created, and a canonical replay — with no brief or a different brief — reconciles exactly as before, never comparing or overwriting the stored brief, and never appearing in differingFields. The promotion endpoint stores a supplied brief even while the SalesBrief feature toggle is disabled; only the form and read API are gated.

Unknown locations or campaigns return 404. Inactive locations and finished campaigns return 422, including a replay after the selection has become ineligible. Invalid input returns 400. The feature being disabled returns 404.

Response

{
  "leadExternalReference": "dark-handoff-100",
  "opportunityExternalReference": "opp_opaque_reference",
  "leadCreated": true,
  "opportunityCreated": true
}

Responses contain external references only, never CRM UUIDs. The same reference string may be used by another tenant, but a tenant can only select and promote records in its own CRM database.

Lead Read API

Bounded read of a Lead by its opaque external reference for trusted callers. Available only when the SalesBrief feature is enabled for the current tenant; disabled access returns 404. The response contains exactly the external reference, business name, SalesBrief, and optional contact email and phone — never CRM UUIDs, contact-person names, or other PII.

Read a Lead by External Reference

GET /Api/external/leads/{externalReference}

Authentication uses the apiKey header. The request host selects the tenant database. The read is read-only — it never recomputes or rewrites anything.

Response

{
  "externalReference": "lead_opaque_reference",
  "businessName": "Example Business",
  "salesBrief": "Sales-ready snapshot...",
  "contactEmail": "contact@example.test",
  "contactPhone": "01234 567890"
}

salesBrief, contactEmail, and contactPhone are null when the Lead has none stored.

Errors

401 — missing, wrong, or cross-tenant API key
404 — feature disabled, Lead missing, or foreign-tenant reference

Lead Conversion API

Convert a Lead using the tenant's saved Lead Conversion Configuration. The API does not accept mapping JSON from callers. Authentication uses the apiKey header, and the request host selects the tenant database.

Convert a Lead

POST /Api/lead/{leadId}/convert

The body may be empty or may contain only an optional Customer status ID:

{
  "statusId": "550e8400-e29b-41d4-a716-446655440002"
}

On success, the existing response shape is preserved:

{ "success": true }

401 — missing or invalid API key
404 — Lead does not exist for the current tenant
400 — Lead is already converted or the Customer status is invalid

sure-cli lead convert --id calls this route directly. --email first resolves the Lead through the Lead email lookup, then calls the same route. MVC, API, and CLI conversion therefore use the same server-side apply operation and persist equivalent results.

Lead Status API

Lead statuses are maintained in the shared, tenant-local status lookup. Lead status inputs accept a status name or the matching Lead status GUID. Responses continue to return the status name, so the public contract remains compatible with existing integrations. Required names are tenant data; a missing or renamed required row makes that operation fail. Customer status IDs and Customer-typed lookup rows are not valid Lead statuses.

The stable cross-product wire names are New, Processing, BuildFailed, and ReadyForEmail. Automation responses expose these names only and do not expose CRM UUIDs.

Change Lead Status

POST /Api/lead/{leadId}/status

{
  "status": "Processing",
  "notes": "optional note"
}

status may be a Lead status name or the matching Lead status GUID. An unknown name or a GUID that does not identify a Lead status is rejected with 400; the Lead is not changed.

Lead Status List API

Bounded, status-filtered Lead listing for automated sample-site claiming. Available only when the AutomatedSampleSiteClaim feature is enabled for the current tenant. Disabled access returns 404. Responses contain opaque external references only — never CRM UUIDs, campaign IDs, contact details, or other PII.

List Leads by Status

GET /Api/leads/byStatus?status={status}

Parameter	Required	Notes
`status`	Yes	Lead status name (case-insensitive), e.g. `New` or `Processing`, or the matching Lead status GUID. Numeric values and comma-separated combinations are rejected (`400`).
`pageSize`	No	Defaults to `20`. Values above `20` are clamped to `20`; values below `1` become `1`.
`cursor`	No	Opaque position data from a previous `nextCursor`; do not edit or rely on its contents. Malformed cursors return `400`.
`hasSalesBrief`	No	When `true`, restricts results to Leads that have a SalesBrief. Null, blank, or whitespace-only briefs are not brief-ready. Omitted or `false` keeps current behaviour exactly.

Results are ordered oldest first by (createdAt, externalReference) and are tenant-isolated by the request host. Listing is read-only — it does not change Lead status, attempt counts, or ownership. Authentication uses the apiKey header.

Response

{
  "leads": [
    {
      "externalReference": "lead_opaque_reference",
      "status": "New",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "opaque-or-null"
}

nextCursor is null on the last page. Walk pages by passing the previous nextCursor until it is null. Do not invent or edit cursors.

Errors

401 — missing, wrong, or cross-tenant API key
400 — missing/invalid status name or GUID, or malformed cursor
404 — feature disabled for the tenant

Lead Claim API

Atomic per-Lead compare-and-set claim for automated sample-site claiming. Available only when the AutomatedSampleSiteClaim feature is enabled for the current tenant. Disabled access returns 404. The Lead is identified solely by its opaque external reference — never a CRM UUID. A successful claim transitions the tenant's New status to Processing only when the Lead is still New.

Claim Lead by External Reference

POST /Api/leads/claim

{
  "externalReference": "lead_opaque_reference"
}

Authentication uses the apiKey header. The request host selects the tenant database. Exactly one of concurrent claim attempts wins; the rest receive 409. The claim updates only the Lead status column.

Response

{
  "externalReference": "lead_opaque_reference",
  "status": "Processing"
}

Responses contain the opaque external reference and new status only — never CRM UUIDs, campaign IDs, contact details, or other PII.

Errors

401 — missing, wrong, or cross-tenant API key
400 — missing or blank external reference
404 — feature disabled, Lead missing, or foreign-tenant reference
409 — Lead exists but is no longer New (bounded conflict; does not reveal the current status beyond "not New")

Lead Build Failure API

Bounded, idempotent BuildFailed report for automated sample-site production. Available only when the AutomatedSampleSiteClaim feature is enabled for the current tenant. Disabled access returns 404. The Lead is identified solely by its opaque external reference — never a CRM UUID. A successful report atomically transitions Processing → BuildFailed and stores exactly one bounded LeadActivityHistory reason: the status change and the activity commit together or roll back together.

Report a Build Failure by External Reference

POST /Api/leads/sample-site/failure

{
  "externalReference": "lead_opaque_reference",
  "reason": "bounded non-leaking failure reason"
}

Authentication uses the apiKey header. The request host selects the tenant database. The reason is required, trimmed, and limited to 500 characters; it is stored once in LeadActivityHistory and is never returned, logged, or metered. If the activity cannot be stored the whole report fails and the Lead remains Processing with no activity. Replays against an already BuildFailed Lead return the same success only when the durable failure activity already exists, without overwriting the stored reason or duplicating activity. The report writes only the Lead status column plus that single activity row.

Response

{
  "externalReference": "lead_opaque_reference",
  "status": "BuildFailed"
}

Responses contain the opaque external reference and status only — never CRM UUIDs, campaign IDs, reason text, contact details, or other PII.

Errors

401 — missing, wrong, or cross-tenant API key
400 — blank external reference, or missing/blank/oversized (over 500 characters) reason
404 — feature disabled, Lead missing, or foreign-tenant reference
409 — Lead exists but is neither Processing nor a BuildFailed Lead with a durable failure activity (bounded conflict; does not reveal the current status, reference, or reason)

Sample-site Completion API

Atomic, idempotent completion for an externally delivered sample site. It is available only when the AutomatedSampleSiteClaim feature is enabled for the current tenant. Disabled access returns 404. The request identifies a Lead only by its opaque external reference — never a CRM UUID.

Surely CRM remains the source of truth for the Lead status and site URL fields. The external Orchestrator calls this public API after delivery; it does not write that CRM state outside this endpoint.

Complete Sample Sites by External Reference

POST /Api/leads/sample-site/completion

The existing single-site request remains supported:

{
  "externalReference": "lead_opaque_reference",
  "url": "https://example-sample.clydewyre.co.uk/"
}

To record several successful sites, send the batch form. urls is ordered and may be empty. The order is retained for delivery results; completion never chooses a PreferredSite, and an existing human choice is preserved. Do not send url with this form.

{
  "externalReference": "lead_opaque_reference",
  "urls": [
    "https://first-example-sample.clydewyre.co.uk/",
    "https://second-example-sample.clydewyre.co.uk/"
  ],
  "minimumSuccessfulSites": 3
}

Authentication uses the apiKey header and the request host selects the tenant database. Every URL must be raw, absolute HTTPS, whitespace-free, at most 500 characters, and distinct. The minimum must be a positive integer. Mixed, incomplete, or invalid forms return 400.

On the first request, the CRM atomically stores every URL one per line in SampleSiteUrls, leaves PreferredSite unchanged, and writes one fixed StatusChanged activity. It changes Processing → ReadyForEmail when the number of URLs reaches the supplied minimum; otherwise it changes to BuildFailed. If the activity cannot be stored, all changes roll back. The marker is:

{
  "previousStatus": "Processing",
  "newStatus": "ReadyForEmail or BuildFailed",
  "source": "ExternalSampleSiteCompletion"
}

An exact replay succeeds only when the stored status, ordered URL text, treating CRLF and LF line endings as equivalent, and durable endpoint marker match the request. The stored PreferredSite is intentionally ignored, so a later human choice does not turn an otherwise identical retry into a conflict. A different URL, URL order, result status, or missing marker returns a generic non-leaking 409 without mutation. This applies to both the batch and legacy single-site forms.

Response

{
  "status": "ReadyForEmail"
}

The status is ReadyForEmail at the batch threshold and BuildFailed below it. The response is status-only. It never returns the external reference, URL, CRM UUID, campaign ID, business name, contact data, or other PII. Application logs and metric tags are aggregate-only and likewise never include those values.

Errors

401 — missing, wrong, or cross-tenant API key
400 — blank external reference, an invalid URL, duplicate batch URLs, a non-positive minimum, or mixed/incomplete request forms
404 — feature disabled, Lead missing, or foreign-tenant reference
409 — an existing Lead is not Processing, or its durable completion state does not exactly match the submitted result; the response does not reveal the Lead state or stored data, and the conflict does not mutate the Lead

Lead Tasks API

Create and manage tasks linked to leads. Tasks support assignment, due dates, priorities, and status tracking.

List Lead Tasks

curl -X GET "https://app.surelycrm.co.uk/Api/lead-tasks?search=&leadId=&assignedToUserId=&status=&priority=&page=1" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Lead Task by Id

curl -X GET "https://app.surelycrm.co.uk/Api/lead-tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Get Tasks for Lead

curl -X GET "https://app.surelycrm.co.uk/Api/leads/550e8400-e29b-41d4-a716-446655440000/tasks" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000"

Create Lead Task

curl -X POST "https://app.surelycrm.co.uk/Api/lead-tasks" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Follow up call",
    "description": "Call to discuss proposal",
    "assignedToUserId": "550e8400-e29b-41d4-a716-446655440001",
    "status": "NotStarted",
    "priority": "High",
    "dueDate": "2026-08-10"
  }'

Update Lead Task

curl -X PUT "https://app.surelycrm.co.uk/Api/lead-tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Follow up call",
    "status": "InProgress",
    "priority": "High",
    "dueDate": "2026-08-10"
  }'

Change Lead Task Status

curl -X POST "https://app.surelycrm.co.uk/Api/lead-tasks/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Content-Type: application/json" \
  -H "apiKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "status": "Completed"
  }'

Need more endpoints? Contact SurelyCrm Support to discuss custom API integrations or webhook requirements.