Skip to main content
POST
/
v1
/
assess
Score conversation
curl --request POST \
  --url https://api.craftcx.com/v1/assess \
  --header 'Content-Type: application/json' \
  --data '
{
  "ticket_id": "ticket_123",
  "messages": [
    {
      "external_id": "msg_1",
      "kind": "message",
      "content": "Why was I charged twice?",
      "author": {
        "type": "contact",
        "external_id": "cus_123",
        "name": "Jane Customer"
      },
      "timestamp": 1700000000000
    },
    {
      "external_id": "msg_2",
      "kind": "message",
      "content": "I can help with billing.",
      "author": {
        "type": "ai",
        "external_id": "billing-agent",
        "name": "Billing Bot"
      },
      "ai_tool": "custom",
      "timestamp": 1700000001000
    },
    {
      "external_id": "note_1",
      "kind": "comment",
      "content": "Escalated to billing for license review.",
      "author": {
        "type": "teammate",
        "external_id": "tea_123",
        "name": "Jason"
      },
      "timestamp": 1700000002000
    }
  ]
}
'
{
  "id": "pfh0haxfpzowht3oi213cqos",
  "external_ticket_id": "ticket_123",
  "source": "zendesk",
  "status": "accepted"
}

Body

application/json
​
ticket_id
string
required

Stable ticket or conversation ID from the source system. CraftCX rejects duplicate imports for the same source and ticket_id.

Minimum string length: 1
Example:

"ticket_123"

​
messages
object[]
required

Conversation transcript items in chronological order. Each item requires external_id, kind, content, author, and timestamp. Use kind=comment for internal notes.

Required array length: 1 - 50 elements
Example:
[
  {
    "external_id": "msg_1",
    "kind": "message",
    "content": "Why was I charged twice?",
    "author": {
      "type": "contact",
      "external_id": "cus_123",
      "name": "Jane Customer"
    },
    "timestamp": 1700000000000
  },
  {
    "external_id": "msg_2",
    "kind": "message",
    "content": "I can help with billing.",
    "author": {
      "type": "ai",
      "external_id": "billing-agent",
      "name": "Billing Bot"
    },
    "ai_tool": "custom",
    "timestamp": 1700000001000
  },
  {
    "external_id": "note_1",
    "kind": "comment",
    "content": "Escalated to billing for license review.",
    "author": {
      "type": "teammate",
      "external_id": "tea_123",
      "name": "Jason"
    },
    "timestamp": 1700000002000
  }
]
​
source
string
default:custom

Source system for this import. Defaults to custom. CraftCX uses source with ticket_id and message external_id to identify imports and reject duplicates.

Minimum string length: 1
Example:

"zendesk"

​
subject
string

Optional ticket or conversation subject from the source system.

Example:

"Billing question"

Response

The ingested event receipt. Note; we aim to 
    respond as quickly as possible, so we return a 202 Accepted 
    status code, and process the event asynchronously.
​
id
string
required

The CraftCX ticket ID for the accepted import.

Example:

"pfh0haxfpzowht3oi213cqos"

​
external_ticket_id
string
required

The ticket ID from the source system.

Example:

"ticket_123"

​
source
string
required

The source namespace used for import identity.

Example:

"zendesk"

​
status
enum<string>
required

The import receipt status.

Available options:
accepted
Example:

"accepted"