Integrations

7 endpoints, each with examples that open in the console prefilled.

All resourcesGuide: Receive events from your app

GET/api/v1/integrationsintegrations:readTry in console

List integrations

List outbound HTTP integrations, newest first, with cursor pagination.

Query parameters

status	string
business_id	string

Filters: status= (active | paused | errored) and business_id= (must belong to the workspace).
Signing secrets are never returned; has_secret tells you whether one is set.
A connection made by signing in to a system from Blueticked (Xero, for example) carries connector_key, connection_state (pending, connected, expiring, needs_reauth or revoked), connection_state_since, connection_state_reason in words and external_account_label, the company chosen at the vendor. Every other connection reads null for all five. The list leaves out a sign-in that was started and not finished (pending). The vendor's tokens are never returned.
Each item is the full public integration shape: alongside the fields shown it also carries the field/response maps, custom headers, inbound settings, credential/health timestamps and counters. Secret ciphertext and hashes are never included.

curl -X GET "https://app.blueticked.com/api/v1/integrations?status=active" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "data": [
    {
      "organization_id": "5b8ec566-3d60-45a0-b4ad-688c9386f289",
      "auth_config": {},
      "sample_payload": {},
      "headers": {},
      "field_map": [],
      "response_map": [],
      "inbound_field_map": [],
      "inbound_enabled": false,
      "credential_updated_at": null,
      "credential_updated_by": null,
      "inbound_token_hint": null,
      "inbound_last_at": null,
      "inbound_last_status": null,
      "inbound_target_channel": null,
      "last_success_at": null,
      "last_failure_at": null,
      "last_delivery_at": "2026-07-02T10:15:00.000Z",
      "last_health_alert_at": null,
      "last_test_status": null,
      "last_test_at": null,
      "last_error": null,
      "last_response_status": null,
      "id": "75cafe56-e3f9-4253-8f2b-c51090d65540",
      "business_id": "22222222-2222-4222-9222-222222222222",
      "name": "Booking CRM",
      "description": null,
      "kind": "crm_api",
      "status": "active",
      "method": "POST",
      "endpoint_url": "https://api.example.com/blueticked/hook",
      "auth_type": "signature",
      "has_secret": true,
      "health_status": "healthy",
      "success_count": 42,
      "failure_count": 0,
      "timeout_ms": 10000,
      "created_at": "2026-07-01T08:00:00.000Z",
      "updated_at": "2026-07-02T10:15:00.000Z",
      "connector_key": null,
      "connection_state": null,
      "connection_state_since": null,
      "connection_state_reason": null,
      "external_account_label": null
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

POST/api/v1/integrationsintegrations:writeTry in console

Create an integration

Create an outbound HTTP integration. It starts paused; test-fire it, then resume to go live.

Body parameters

namerequired	string
kind	string
business_id	string
method	string
endpoint_urlrequired	string
auth_type	string
auth_secret	string
timeout_ms	number

The integration is returned FLAT (fields at the top level, no integration wrapper), the same public shape as GET /api/v1/integrations/{id} and each list item.
Endpoints must be public https URLs (SSRF-guarded; private/internal hosts are rejected).
The auth secret is accepted once and sealed; it is never returned. Omit business_id to attach to the default business.
auth_type is one of none, signature, bearer, api_key (defaults to signature). signature generates a secret when you omit one; bearer / api_key require you to supply one; none sends no auth headers.

curl -X POST "https://app.blueticked.com/api/v1/integrations" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: change-me-per-request-0001" \
  -d '{
  "name": "Booking CRM",
  "kind": "crm_api",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "method": "POST",
  "endpoint_url": "https://api.example.com/blueticked/hook",
  "auth_type": "signature",
  "auth_secret": "your-signing-secret",
  "timeout_ms": 10000
}'

Response

{
  "organization_id": "5b8ec566-3d60-45a0-b4ad-688c9386f289",
  "auth_config": {},
  "sample_payload": {},
  "headers": {},
  "field_map": [],
  "response_map": [],
  "inbound_field_map": [],
  "inbound_enabled": false,
  "credential_updated_at": null,
  "credential_updated_by": null,
  "inbound_token_hint": null,
  "inbound_last_at": null,
  "inbound_last_status": null,
  "inbound_target_channel": null,
  "last_success_at": null,
  "last_failure_at": null,
  "last_delivery_at": null,
  "last_health_alert_at": null,
  "last_test_status": null,
  "last_test_at": null,
  "last_error": null,
  "last_response_status": null,
  "id": "75cafe56-e3f9-4253-8f2b-c51090d65540",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "name": "Booking CRM",
  "description": null,
  "kind": "crm_api",
  "status": "paused",
  "method": "POST",
  "endpoint_url": "https://api.example.com/blueticked/hook",
  "auth_type": "signature",
  "has_secret": true,
  "health_status": "unknown",
  "success_count": 0,
  "failure_count": 0,
  "timeout_ms": 10000,
  "created_at": "2026-07-01T08:00:00.000Z",
  "updated_at": "2026-07-01T08:00:00.000Z",
  "connector_key": null,
  "connection_state": null,
  "connection_state_since": null,
  "connection_state_reason": null,
  "external_account_label": null,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

GET/api/v1/integrations/{id}integrations:readTry in console

Get an integration

Fetch a single integration's public configuration and health.

The integration is returned FLAT (fields at the top level, no integration wrapper).
No ciphertext or hash columns are ever returned.

curl -X GET "https://app.blueticked.com/api/v1/integrations/{id}" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "organization_id": "5b8ec566-3d60-45a0-b4ad-688c9386f289",
  "auth_config": {},
  "sample_payload": {},
  "headers": {},
  "field_map": [],
  "response_map": [],
  "inbound_field_map": [],
  "inbound_enabled": false,
  "credential_updated_at": null,
  "credential_updated_by": null,
  "inbound_token_hint": null,
  "inbound_last_at": null,
  "inbound_last_status": null,
  "inbound_target_channel": null,
  "last_success_at": null,
  "last_failure_at": null,
  "last_delivery_at": "2026-07-02T10:15:00.000Z",
  "last_health_alert_at": null,
  "last_test_status": null,
  "last_test_at": null,
  "last_error": null,
  "last_response_status": null,
  "id": "75cafe56-e3f9-4253-8f2b-c51090d65540",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "name": "Booking CRM",
  "description": null,
  "kind": "crm_api",
  "status": "active",
  "method": "POST",
  "endpoint_url": "https://api.example.com/blueticked/hook",
  "auth_type": "signature",
  "has_secret": true,
  "health_status": "healthy",
  "success_count": 42,
  "failure_count": 0,
  "timeout_ms": 10000,
  "created_at": "2026-07-01T08:00:00.000Z",
  "updated_at": "2026-07-02T10:15:00.000Z",
  "connector_key": null,
  "connection_state": null,
  "connection_state_since": null,
  "connection_state_reason": null,
  "external_account_label": null,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

PATCH/api/v1/integrations/{id}integrations:writeTry in console

Update an integration

Update any subset of an integration's fields, including its live status.

Body parameters

status	string
timeout_ms	number

The integration is returned FLAT (fields at the top level, no integration wrapper).
Send auth_secret to rotate the sealed secret, or clear_auth_secret: true to drop it.
Set status: "active" to resume, "paused" to stop firing.
An integration that only receives events has no outbound mapping: field_map, response_map, method, headers, timeout_ms, auth_secret or auth_header_name on it is refused with 409 conflict and details.reason "receive_only", and nothing is written. Setting a real endpoint_url makes it two-way.

curl -X PATCH "https://app.blueticked.com/api/v1/integrations/{id}" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active",
  "timeout_ms": 15000
}'

Response

{
  "organization_id": "5b8ec566-3d60-45a0-b4ad-688c9386f289",
  "auth_config": {},
  "sample_payload": {},
  "headers": {},
  "field_map": [],
  "response_map": [],
  "inbound_field_map": [],
  "inbound_enabled": false,
  "credential_updated_at": null,
  "credential_updated_by": null,
  "inbound_token_hint": null,
  "inbound_last_at": null,
  "inbound_last_status": null,
  "inbound_target_channel": null,
  "last_success_at": null,
  "last_failure_at": null,
  "last_delivery_at": null,
  "last_health_alert_at": null,
  "last_test_status": null,
  "last_test_at": null,
  "last_error": null,
  "last_response_status": null,
  "id": "75cafe56-e3f9-4253-8f2b-c51090d65540",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "name": "Booking CRM",
  "description": null,
  "kind": "crm_api",
  "status": "active",
  "method": "POST",
  "endpoint_url": "https://api.example.com/blueticked/hook",
  "auth_type": "signature",
  "has_secret": true,
  "health_status": "healthy",
  "success_count": 42,
  "failure_count": 0,
  "timeout_ms": 15000,
  "created_at": "2026-07-01T08:00:00.000Z",
  "updated_at": "2026-07-02T11:00:00.000Z",
  "connector_key": null,
  "connection_state": null,
  "connection_state_since": null,
  "connection_state_reason": null,
  "external_account_label": null,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

DELETE/api/v1/integrations/{id}integrations:writeTry in console

Delete an integration

Soft-delete an integration and stop it firing.

Soft delete: the integration is removed from lists and paused; its delivery history is retained per the retention policy.

curl -X DELETE "https://app.blueticked.com/api/v1/integrations/{id}" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "id": "75cafe56-e3f9-4253-8f2b-c51090d65540",
  "deleted": true,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

GET/api/v1/integrations/{id}/deliveriesintegrations:readTry in console

List integration deliveries

List an integration's delivery attempts (test + live), newest first, with cursor pagination.

Includes the full request/response bodies for replay and debugging. An API key is org-admin-grade for the data it can read.

curl -X GET "https://app.blueticked.com/api/v1/integrations/{id}/deliveries" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "data": [
    {
      "retry_of": null,
      "event_type": null,
      "external_reference": null,
      "message_external_id": null,
      "submitter_phone": null,
      "id": "be8b69f2-ca8d-4b2a-a34c-5d43d34e448f",
      "kind": "live",
      "status": "succeeded",
      "direction": "outbound",
      "attempt": 1,
      "response_status": 200,
      "duration_ms": 214,
      "request_payload": {
        "event": "flow_submission"
      },
      "response_body": "{\"ok\":true}",
      "response_mapped": {},
      "error": null,
      "created_at": "2026-07-02T10:15:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

POST/api/v1/integrations/{id}/testintegrations:writeTry in console

Test-fire an integration

Send a signed test delivery to the endpoint. On success the integration is switched to active.

Body parameters

response_fields

object

Works on a paused integration so you can verify it before going live; a passing test flips it to active.
Rate limited to 10 requests per minute per key, because this makes a real outbound HTTP call.
passed is false (with error) when the endpoint returns a non-2xx or the request fails; the HTTP status is always 200.
An integration that only receives events has no address of its own to test: it is refused with 409 conflict and details.reason "receive_only", and its health is left as it was. Send a sample event from the app to its callback URL instead.

curl -X POST "https://app.blueticked.com/api/v1/integrations/{id}/test" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "response_fields": {
    "full_name": "Test Patient",
    "phone": "+27000000000"
  }
}'

Response

{
  "payload": {
    "event": "booking.created"
  },
  "passed": true,
  "delivery_id": "be8b69f2-ca8d-4b2a-a34c-5d43d34e448f",
  "status": 200,
  "response_body": "{\"ok\":true}",
  "response_mapped": {},
  "duration_ms": 214,
  "error": null,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}