```html Lead Intake API Documentation

Lead Intake API

Use this API to submit new client leads and automatically create the associated claim.

Contents

Endpoint Authentication Request Body Name Fields Example Requests Success Response Error Responses cURL Example Important Notes

Endpoint

POST /api/leads/{key}

The {key} is your unique endpoint key. This identifies the endpoint, solicitor and lead source configuration. 

https://ha.fintrixor.co.uk/api/leads/YOUR_ENDPOINT_KEY

Authentication

Authentication requires both:

Send the API key using the Authorization header:

Authorization: Bearer YOUR_API_KEY
Invalid or inactive endpoint keys return 404 Not Found. Missing or invalid API keys return 401 Unauthorized.

Request Body

The request body must be sent as JSON using the Content-Type: application/json header.

Field Required Type Example Notes
reference Optional string EXT-123 Your external reference for the lead.
full_name Conditional string Mr John Edward Smith Required if first_name and last_name are not provided.
title Optional string Mr Can also be extracted from full_name if supplied.
first_name Conditional string John Required with last_name if full_name is not provided.
middle_name Optional string|null Edward Optional middle name.
last_name Conditional string Smith Required with first_name if full_name is not provided.
preferred_name Optional string|null Johnny Optional preferred name.
dob Optional date 1985-05-20 Use YYYY-MM-DD format.
landline_number Conditional string 01511234567 Required when phone_number is not provided. Must be a valid UK landline number.
email Required string john@example.com Must be a valid email address.
phone_number Conditional string +447123456789 Required when landline_number is not provided. Spaces are removed automatically.
what_type_of_care_were_you_in Optional string|null Foster care If supplied, this is saved as a note against the client.
anything_you_wish_to_tell_us Optional string|null I moved between several foster placements. If supplied, this is saved as a note against the client.

Name Fields

The API accepts names in one of two formats.

Option 1: Send full_name

Use this when the lead provider stores the client name as a single field. 

{
  "full_name": "Mr John Smith"
}

The API will attempt to split the full name into:

Option 2: Send first_name and last_name

Use this when the lead provider stores first and last names separately. 

{
  "first_name": "John",
  "last_name": "Smith"
}
A request must include either full_name, or both first_name and last_name. Sending only a first name or only a last name will return a 422 Validation Error.

Supported titles in full_name

The following titles are recognised when supplied at the start of full_name: 

Mr, Mrs, Ms, Miss, Dr, Prof, Rev, Sir, Lady, Lord, Mx

Example Requests

Example using first and last name

{
  "reference": "EXT-123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "preferred_name": null,
  "dob": "1985-05-20",
  "email": "john@example.com",
  "phone": "+447123456789",
  "what_type_of_care_were_you_in": "Foster care",
  "anything_you_wish_to_tell_us": "I moved between several foster placements."
}

Example using full name

{
  "reference": "EXT-124",
  "full_name": "Ms Jane Smith",
  "dob": "1990-03-14",
  "email": "jane@example.com",
  "phone": "+447987654321",
  "what_type_of_care_were_you_in": "Residential care",
  "anything_you_wish_to_tell_us": null
}

Success Response

Status: 201 Created

A successful request creates both a Client and a Claim. 
{
  "success": true,
  "message": "Client and claim created successfully.",
  "data": {
    "client_id": 123,
    "claim_id": 456,
    "reference": "EXT-123"
  }
}

Error Responses

401 Unauthorized

Returned when the API key is missing, invalid or inactive. 

{
  "message": "Unauthorized."
}

404 Not Found

Returned when the endpoint key is invalid or inactive. 

{
  "message": "Endpoint not found."
}

422 Validation Error

Returned when the submitted data does not pass validation. 

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "Either full name or both first name and last name are required."
    ]
  }
}

422 Validation Error: Missing last name

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name must include both a first name and last name."
    ]
  }
}

422 Validation Error: Invalid phone

{
  "message": "The given data was invalid.",
  "errors": {
    "phone": [
      "The phone format is invalid."
    ]
  }
}

cURL Example

Using first and last name

curl -X POST https://ha.fintrixor.co.uk/api/leads/YOUR_ENDPOINT_KEY \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "reference": "EXT-123",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Smith",
    "dob": "1985-05-20",
    "email": "john@example.com",
    "phone": "+447123456789"
  }'

Using full name

curl -X POST https://ha.fintrixor.co.uk/api/leads/YOUR_ENDPOINT_KEY \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "reference": "EXT-124",
    "full_name": "Ms Jane Smith",
    "dob": "1990-03-14",
    "email": "jane@example.com",
    "phone": "+447987654321"
  }'

Important Notes

```