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

API Key Authentication

The /Api/Create endpoint accepts 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

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	No	Auto-generated if omitted
address1	string	Yes	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	Yes	Town
city	string	Yes	City
postcode	string	Yes	Postcode
homePhone	string	No	Home telephone number
mobilePhone	string	No	Mobile telephone number
emailAddress	string	Yes	Email address
notificationsEnabled	boolean	Yes	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:

{
  "Firstname": ["The Firstname field is required."],
  "EmailAddress": ["The EmailAddress field is required."]
}

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

Returns matching customer count and sample before execution.

POST /BulkAction/Preview

Body:
{
  "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": {
    "totalCustomersMatched": 245,
    "sampleCustomers": [ /* first 10 matches */ ]
  }
}

Create Bulk Action Job

POST /BulkAction/CreateJob

Body:
{
  "actionRequest": {
    "actionType": "Email",
    "useTemplate": true,
    "emailTemplateId": "guid",
    "filter": { /* same filter structure as Preview */ }
  }
}

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
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"
  }'