Surfaces

List Surfaces

get

List surfaces with pagination and optional filters.

Permissions: viewer, member, admin, owner (surfaces:read)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

entity_idstring · uuid · nullableOptional

Filter by entity ID

statusstring · nullableOptional

Filter by status

channelstring · nullableOptional

Filter by channel

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/surfaces

GET /v1/{workspace_id}/surfaces HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "event_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "description": "text",
      "status": "created",
      "channel": "email",
      "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
      "fields_count": 1,
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "resource_type": "text",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "expires_at": "text",
      "created_at": "text",
      "delivered_at": "text",
      "opened_at": "text",
      "submitted_at": "text",
      "submitted_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "delivery_metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "review_notes": "text",
      "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
      "reviewed_at": "text",
      "archived_at": "text",
      "archive_reason": "text",
      "url": "text"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create Surface

post

Create a new data collection surface.

Stores the surface spec as a world.event with domain="surface". The entity_id is stored inside event data (not on the event row) to avoid entity state recomputation.

Returns a signed patient-facing token and URL if SURFACE_TOKEN_SECRET is configured.

Permissions: member, admin, owner (surfaces:write)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Request to create a new surface.

The agent generates a SurfaceSpec and sends it here.

entity_idstring · uuidRequired

titlestring · min: 1 · max: 256Required

descriptionstring · max: 2000 · nullableOptional

channelstring · enumOptional

Delivery channels for surfaces.

Default: webPossible values:

use_case_idstring · uuid · nullableOptional

expires_in_hoursinteger · min: 1 · max: 8760OptionalDefault: 168

resource_typestring · max: 64 · nullableOptional

completion_titlestring · max: 256 · nullableOptional

completion_messagestring · max: 2000 · nullableOptional

completion_action_urlstring · max: 2048 · nullableOptional

submit_button_textstring · max: 128 · nullableOptional

Responses

200

Successful Response

application/json

idstring · uuidRequired

event_idstring · uuidRequired

entity_idstring · uuidRequired

titlestringRequired

descriptionstring · nullableOptional

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

channelstring · enumRequired

Delivery channels for surfaces.

Possible values:

use_case_idstring · uuid · nullableOptional

fields_countintegerRequired

expires_atstringRequired

created_atstringRequired

tokenstring · nullableOptional

urlstring · nullableOptional

422

Validation error

429

Rate limited

post/v1/{workspace_id}/surfaces

POST /v1/{workspace_id}/surfaces HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 892

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "fields": [
    {
      "key": "text",
      "label": "text",
      "field_type": "text",
      "required": true,
      "options": [
        "text"
      ],
      "description": "text",
      "placeholder": "text",
      "prefill_value": null,
      "validation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "sensitive": false,
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "consent_text": "text"
    }
  ],
  "channel": "web",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_in_hours": 168,
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "resource_type": "text",
  "branding": {
    "logo_url": "text",
    "primary_color": "text",
    "background_color": "text",
    "font_family": "text"
  },
  "sections": [
    {
      "title": "text",
      "description": "text",
      "field_keys": [
        "text"
      ],
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "completion_title": "text",
  "completion_message": "text",
  "completion_action_url": "text",
  "submit_button_text": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "expires_at": "text",
  "created_at": "text",
  "token": "text",
  "url": "text"
}

List surfaces pending review

get

List surfaces pending review.

Field engineers use this to approve or reject surfaces before delivery.

Permissions: operator, member, admin, owner (ReviewQueue:View)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/surfaces/review

GET /v1/{workspace_id}/surfaces/review HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "event_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "description": "text",
      "status": "created",
      "channel": "email",
      "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
      "fields_count": 1,
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "resource_type": "text",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "expires_at": "text",
      "created_at": "text",
      "delivered_at": "text",
      "opened_at": "text",
      "submitted_at": "text",
      "submitted_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "delivery_metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "review_notes": "text",
      "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
      "reviewed_at": "text",
      "archived_at": "text",
      "archive_reason": "text",
      "url": "text"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get Surface

get

Get a surface by ID.

Returns the surface spec and current lifecycle status. Also mints the patient-facing url so operators can copy/share the link from the read view (the token isn't stored, so it's re-minted on each read).

Permissions: viewer, member, admin, owner (surfaces:read)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

event_idstring · uuidRequired

entity_idstring · uuid · nullableOptional

titlestring · nullableOptional

descriptionstring · nullableOptional

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:

use_case_idstring · uuid · nullableOptional

fields_countintegerRequired

resource_typestring · nullableOptional

expires_atstring · nullableOptional

created_atstring · nullableOptional

delivered_atstring · nullableOptional

opened_atstring · nullableOptional

submitted_atstring · nullableOptional

review_notesstring · nullableOptional

reviewed_bystring · uuid · nullableOptional

reviewed_atstring · nullableOptional

archived_atstring · nullableOptional

archive_reasonstring · nullableOptional

urlstring · nullableOptional

404

Surface not found

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/surfaces/{surface_id}

GET /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "fields": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "resource_type": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "expires_at": "text",
  "created_at": "text",
  "delivered_at": "text",
  "opened_at": "text",
  "submitted_at": "text",
  "submitted_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "delivery_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "review_notes": "text",
  "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
  "reviewed_at": "text",
  "archived_at": "text",
  "archive_reason": "text",
  "url": "text"
}

Archive (soft-delete) a surface

delete

Archive (soft-delete) a surface.

Works for any non-terminal surface. Terminal surfaces (completed, expired, already archived) cannot be archived.

Permissions: member, admin, owner (Surface:Create)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

surface_idstring · uuidRequired

statusconst: archivedRequired

404

Surface not found

409

Cannot archive terminal surface

422

Validation Error

application/json

429

Rate limited

delete/v1/{workspace_id}/surfaces/{surface_id}

DELETE /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "text"
}

Update a surface spec

patch

Update an existing surface spec.

Only allowed while status is CREATED or DELIVERED. Writes a surface.updated event preserving the full audit trail.

Permissions: member, admin, owner (Surface:Create)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Body

Partial update to an existing surface.

All fields are optional. Only provided fields are merged into the spec. Only allowed while status is CREATED or DELIVERED.

titlestring · min: 1 · max: 256 · nullableOptional

descriptionstring · max: 2000 · nullableOptional

completion_titlestring · max: 256 · nullableOptional

completion_messagestring · max: 2000 · nullableOptional

completion_action_urlstring · max: 2048 · nullableOptional

submit_button_textstring · max: 128 · nullableOptional

channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:

resource_typestring · max: 64 · nullableOptional

Responses

200

Successful Response

application/json

idstring · uuidRequired

event_idstring · uuidRequired

entity_idstring · uuid · nullableOptional

titlestring · nullableOptional

descriptionstring · nullableOptional

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:

use_case_idstring · uuid · nullableOptional

fields_countintegerRequired

resource_typestring · nullableOptional

expires_atstring · nullableOptional

created_atstring · nullableOptional

delivered_atstring · nullableOptional

opened_atstring · nullableOptional

submitted_atstring · nullableOptional

review_notesstring · nullableOptional

reviewed_bystring · uuid · nullableOptional

reviewed_atstring · nullableOptional

archived_atstring · nullableOptional

archive_reasonstring · nullableOptional

urlstring · nullableOptional

404

Surface not found

409

Cannot update in current status

422

Validation error

429

Rate limited

patch/v1/{workspace_id}/surfaces/{surface_id}

PATCH /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 718

{
  "title": "text",
  "description": "text",
  "fields": [
    {
      "key": "text",
      "label": "text",
      "field_type": "text",
      "required": true,
      "options": [
        "text"
      ],
      "description": "text",
      "placeholder": "text",
      "prefill_value": null,
      "validation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "sensitive": false,
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "consent_text": "text"
    }
  ],
  "branding": {
    "logo_url": "text",
    "primary_color": "text",
    "background_color": "text",
    "font_family": "text"
  },
  "sections": [
    {
      "title": "text",
      "description": "text",
      "field_keys": [
        "text"
      ],
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "completion_title": "text",
  "completion_message": "text",
  "completion_action_url": "text",
  "submit_button_text": "text",
  "channel": "email",
  "resource_type": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "fields": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "resource_type": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "expires_at": "text",
  "created_at": "text",
  "delivered_at": "text",
  "opened_at": "text",
  "submitted_at": "text",
  "submitted_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "delivery_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "review_notes": "text",
  "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
  "reviewed_at": "text",
  "archived_at": "text",
  "archive_reason": "text",
  "url": "text"
}

Approve a surface pending review

post

Approve a surface pending review.

The surface returns to CREATED status and can then be delivered.

Permissions: operator, member, admin, owner (ReviewQueue:Review)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

surface_idstring · uuidRequired

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

actionstring · enumRequiredPossible values:

404

Surface not found

409

Surface is not pending review

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/surfaces/{surface_id}/approve

POST /v1/{workspace_id}/surfaces/{surface_id}/approve HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "action": "approved"
}

Reject a surface pending review

post

Reject a surface pending review.

The surface is marked as expired and will not be delivered.

Permissions: operator, member, admin, owner (ReviewQueue:Review)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Body

reasonstring · max: 2000 · nullableOptional

Responses

200

Successful Response

application/json

surface_idstring · uuidRequired

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

actionstring · enumRequiredPossible values:

404

Surface not found

409

Surface is not pending review

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/surfaces/{surface_id}/reject

POST /v1/{workspace_id}/surfaces/{surface_id}/reject HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "action": "approved"
}

Get field-level completion status

get

Get field-level completion status for a surface.

Returns which fields are filled vs empty, useful for abandonment intelligence and targeted re-engagement.

Permissions: viewer, member, admin, owner (surfaces:read)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

surface_idstring · uuidRequired

total_fieldsintegerRequired

filled_countintegerRequired

empty_countintegerRequired

filled_keysstring[]Required

empty_keysstring[]Required

required_empty_keysstring[]Required

404

Surface not found

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/surfaces/{surface_id}/progress

GET /v1/{workspace_id}/surfaces/{surface_id}/progress HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_fields": 1,
  "filled_count": 1,
  "empty_count": 1,
  "filled_keys": [
    "text"
  ],
  "empty_keys": [
    "text"
  ],
  "required_empty_keys": [
    "text"
  ]
}

Create new surface with only unfilled fields

post

Create a new surface with only the unfilled fields from the original.

Used for re-engaging patients who abandoned a form. The new surface contains only the fields they haven't completed yet, reducing friction.

Permissions: member, admin, owner (surfaces:write)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

event_idstring · uuidRequired

entity_idstring · uuidRequired

titlestringRequired

descriptionstring · nullableOptional

statusstring · enumRequired

Lifecycle status of a surface.

Possible values:

channelstring · enumRequired

Delivery channels for surfaces.

Possible values:

use_case_idstring · uuid · nullableOptional

fields_countintegerRequired

expires_atstringRequired

created_atstringRequired

tokenstring · nullableOptional

urlstring · nullableOptional

404

Surface not found

409

All fields already filled

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/surfaces/{surface_id}/reshape

POST /v1/{workspace_id}/surfaces/{surface_id}/reshape HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "expires_at": "text",
  "created_at": "text",
  "token": "text",
  "url": "text"
}

Deliver Surface

post

Record a real delivery handoff for a surface.

Email targets are delivered through channel-manager's POST /v1/email/ (CM owns SES sender identity, IP pool, DKIM, suppression — keyed on the surface row's use_case_id). Phone-shaped addresses return 422 — SMS surface delivery was removed in PR #2783. Other targets record an external handoff that was completed outside platform-api.

Permissions: member, admin, owner (surfaces:write)

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

surface_idstring · uuidRequired

Body

Request to mark a surface as delivered.

channel_addressstring · min: 1 · max: 256Required

Delivery address (phone number, email, etc.)

Responses

200

Successful Response

application/json

surface_idstring · uuidRequired

statusstring · enumRequiredPossible values:

channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:

urlstring · nullableOptional

channel_addressstringRequired

message_idstring · nullableOptional

from_numberstring · nullableOptional

from_addressstring · nullableOptional

delivery_providerstring · nullableOptional

delivered_atstring · nullableOptional

404

Surface not found

409

Surface already delivered/completed/expired

422

Validation error

429

Rate limited

post/v1/{workspace_id}/surfaces/{surface_id}/deliver

POST /v1/{workspace_id}/surfaces/{surface_id}/deliver HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "channel_address": "text"
}

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "delivered",
  "channel": "email",
  "url": "text",
  "channel_address": "text",
  "message_id": "text",
  "from_number": "text",
  "from_address": "text",
  "delivery_provider": "text",
  "delivered_at": "text"
}