Back to top

API Documentation

Transcribes

Overview

Transcribes are structured records of transcribed conversations (e.g. voice calls or meetings) tied to a contact. Each transcribe stores an ordered list of utterances with a per-line timestamp, author label, and text.

This is the canonical replacement for storing free-form transcripts in contact note attributes.

Transcribe

A Transcribe's data model is described in the table below:

Field Type Association Description
id uuid Internal identifier of the object
created_at number Unix timestamp of creation
updated_at number Unix timestamp of last update
brand uuid The brand this transcribe belongs to
user User transcribe.user The user who recorded/owns this transcribe
contact Contact transcribe.contact The contact the conversation is with
contents Utterance[] Ordered list of transcribed utterances (see below)
created_by uuid User who created this record
updated_by uuid User who last updated this record

Utterance

Each entry of contents is an object describing a single line of the conversation:

Field Type Required Description
timestamp number yes Offset from the start of the conversation, in seconds. Fractional values are allowed.
author string yes Free-form speaker label (e.g. Agent, Client, or a name).
text string yes The transcribed text for this utterance.

Endpoints

List transcribes for a brand

List transcribes for a brand
GET/brands/:id/transcribes

Returns all transcribes belonging to the brand, ordered most-recent-first. Optionally filter by contact.

Query parameters:

Field Type Required Description
contact uuid no When provided, only transcribes for this contact are returned.

Example URI

GET /brands/:id/transcribes
URI Parameters
HideShow
id
string (required) Example: bd3c4f3e-6465-469c-ad30-09b93cabb965
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "2a04242b-e6b6-4f3d-a33b-647007ece360",
      "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "created_at": 1778872342.667593,
      "updated_at": 1778872342.667593,
      "deleted_at": null,
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "updated_by": null,
      "type": "transcribe",
      "entries": [
        {
          "id": "19b02ac1-a57d-46eb-9c6e-4e3b465f531e",
          "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
          "timestamp": 0,
          "author": "Agent",
          "text": "Hi, how can I help you?",
          "created_at": 1778872342.667593,
          "type": "transcribe_entry"
        },
        {
          "id": "c4e73292-ebdf-4e2f-9602-27f64ba0bd7a",
          "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
          "timestamp": 3.5,
          "author": "Client",
          "text": "Looking for a 3-bedroom house.",
          "created_at": 1778872342.667593,
          "type": "transcribe_entry"
        },
        {
          "id": "686c38ce-4f00-4245-89ae-91fbd9973cdc",
          "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
          "timestamp": 7.2,
          "author": "Agent",
          "text": "Great, what is your budget?",
          "created_at": 1778872342.667593,
          "type": "transcribe_entry"
        }
      ]
    },
    {
      "id": "3039748d-aeb9-4d2d-907d-d010c2f055fd",
      "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "created_at": 1778872342.667593,
      "updated_at": 1778872342.667593,
      "deleted_at": null,
      "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "updated_by": null,
      "type": "transcribe",
      "entries": null
    }
  ],
  "info": {
    "count": 2,
    "total": 0
  }
}

Get a specific transcribe

Get a specific transcribe
GET/brands/:id/transcribes/:transcribe

Example URI

GET /brands/:id/transcribes/:transcribe
URI Parameters
HideShow
id
string (required) Example: bd3c4f3e-6465-469c-ad30-09b93cabb965
transcribe
string (required) Example: 2a04242b-e6b6-4f3d-a33b-647007ece360
associations
string (required) Example: transcribe.contact
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "2a04242b-e6b6-4f3d-a33b-647007ece360",
    "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
    "contact": {
      "id": "ff30aa35-9625-4025-bcfc-8f1db854a17c",
      "display_name": "Johnny",
      "partner_name": "Jane Doe",
      "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "brand_id": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "sort_field": "Johnny",
      "last_touch": null,
      "last_touch_action": null,
      "next_touch": null,
      "touch_freq": null,
      "ios_address_book_id": null,
      "android_address_book_id": null,
      "created_at": 1778872344.285793,
      "updated_at": 1778872342.667593,
      "deleted_at": null,
      "created_for": "direct_request",
      "updated_for": "direct_request",
      "deleted_for": null,
      "title": null,
      "first_name": "John",
      "partner_first_name": "Jane",
      "middle_name": "M.",
      "last_name": "Doe",
      "partner_last_name": "Doe",
      "marketing_name": null,
      "nickname": "Johnny",
      "email": "[email protected]",
      "primary_email": "[email protected]",
      "emails": [
        "[email protected]"
      ],
      "parked": false,
      "partner_email": "[email protected]",
      "phone_number": "+989124834198",
      "primary_phone_number": "+989124834198",
      "phone_numbers": [
        "+989124834198"
      ],
      "company": "Rechat",
      "birthday": "1970-01-12T00:00:00.000Z",
      "profile_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "cover_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "job_title": "Contact Test Subject",
      "source_type": "ExplicitlyCreated",
      "source": null,
      "website": [
        "http://www.gholi.com"
      ],
      "tags": [
        "poo",
        "foo",
        "New"
      ],
      "address": [
        {
          "city": "Dallas",
          "full": "Street, Dallas Texas 72890",
          "name": "Street",
          "type": "stdaddr",
          "extra": "Office",
          "line1": "Street",
          "line2": "Dallas Texas 72890",
          "state": "Texas",
          "country": "US",
          "postcode": "72890"
        }
      ],
      "type": "contact"
    },
    "created_at": 1778872342.667593,
    "updated_at": 1778872342.667593,
    "deleted_at": null,
    "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "updated_by": null,
    "type": "transcribe",
    "entries": [
      {
        "id": "19b02ac1-a57d-46eb-9c6e-4e3b465f531e",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 0,
        "author": "Agent",
        "text": "Hi, how can I help you?",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      },
      {
        "id": "c4e73292-ebdf-4e2f-9602-27f64ba0bd7a",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 3.5,
        "author": "Client",
        "text": "Looking for a 3-bedroom house.",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      },
      {
        "id": "686c38ce-4f00-4245-89ae-91fbd9973cdc",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 7.2,
        "author": "Agent",
        "text": "Great, what is your budget?",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      }
    ]
  }
}

Create a transcribe

Create a transcribe
POST/brands/:id/transcribes

Creates a transcribe under the given brand. The contact must belong to the same brand. The contents array may be empty, but when provided every entry must include a timestamp, author, and text.

Body fields:

Field Type Required Description
contact uuid yes The contact this conversation was with
contents Utterance[] yes Ordered list of utterances (may be empty)

Example URI

POST /brands/:id/transcribes
URI Parameters
HideShow
id
string (required) Example: bd3c4f3e-6465-469c-ad30-09b93cabb965
associations
string (required) Example: transcribe.contact,transcribe.entries
Request
HideShow
Body
{
  "contact": "ff30aa35-9625-4025-bcfc-8f1db854a17c",
  "contents": [
    {
      "timestamp": 0,
      "author": "Agent",
      "text": "Hi, how can I help you?"
    },
    {
      "timestamp": 3.5,
      "author": "Client",
      "text": "Looking for a 3-bedroom house."
    },
    {
      "timestamp": 7.2,
      "author": "Agent",
      "text": "Great, what is your budget?"
    }
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "2a04242b-e6b6-4f3d-a33b-647007ece360",
    "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
    "contact": {
      "id": "ff30aa35-9625-4025-bcfc-8f1db854a17c",
      "display_name": "Johnny",
      "partner_name": "Jane Doe",
      "brand": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "brand_id": "bd3c4f3e-6465-469c-ad30-09b93cabb965",
      "user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
      "sort_field": "Johnny",
      "last_touch": null,
      "last_touch_action": null,
      "next_touch": null,
      "touch_freq": null,
      "ios_address_book_id": null,
      "android_address_book_id": null,
      "created_at": 1778872344.285793,
      "updated_at": 1778872342.667593,
      "deleted_at": null,
      "created_for": "direct_request",
      "updated_for": "direct_request",
      "deleted_for": null,
      "title": null,
      "first_name": "John",
      "partner_first_name": "Jane",
      "middle_name": "M.",
      "last_name": "Doe",
      "partner_last_name": "Doe",
      "marketing_name": null,
      "nickname": "Johnny",
      "email": "[email protected]",
      "primary_email": "[email protected]",
      "emails": [
        "[email protected]"
      ],
      "parked": false,
      "partner_email": "[email protected]",
      "phone_number": "+989124834198",
      "primary_phone_number": "+989124834198",
      "phone_numbers": [
        "+989124834198"
      ],
      "company": "Rechat",
      "birthday": "1970-01-12T00:00:00.000Z",
      "profile_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "cover_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "job_title": "Contact Test Subject",
      "source_type": "ExplicitlyCreated",
      "source": null,
      "website": [
        "http://www.gholi.com"
      ],
      "tags": [
        "poo",
        "foo",
        "New"
      ],
      "address": [
        {
          "city": "Dallas",
          "full": "Street, Dallas Texas 72890",
          "name": "Street",
          "type": "stdaddr",
          "extra": "Office",
          "line1": "Street",
          "line2": "Dallas Texas 72890",
          "state": "Texas",
          "country": "US",
          "postcode": "72890"
        }
      ],
      "type": "contact"
    },
    "created_at": 1778872342.667593,
    "updated_at": 1778872342.667593,
    "deleted_at": null,
    "created_by": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
    "updated_by": null,
    "type": "transcribe",
    "entries": [
      {
        "id": "19b02ac1-a57d-46eb-9c6e-4e3b465f531e",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 0,
        "author": "Agent",
        "text": "Hi, how can I help you?",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      },
      {
        "id": "c4e73292-ebdf-4e2f-9602-27f64ba0bd7a",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 3.5,
        "author": "Client",
        "text": "Looking for a 3-bedroom house.",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      },
      {
        "id": "686c38ce-4f00-4245-89ae-91fbd9973cdc",
        "transcribe": "2a04242b-e6b6-4f3d-a33b-647007ece360",
        "timestamp": 7.2,
        "author": "Agent",
        "text": "Great, what is your budget?",
        "created_at": 1778872342.667593,
        "type": "transcribe_entry"
      }
    ]
  }
}

Delete a transcribe

Delete a transcribe
DELETE/brands/:id/transcribes/:transcribe

Soft-deletes a transcribe. Returns 204 on success.

Example URI

DELETE /brands/:id/transcribes/:transcribe
URI Parameters
HideShow
id
string (required) Example: bd3c4f3e-6465-469c-ad30-09b93cabb965
transcribe
string (required) Example: 2a04242b-e6b6-4f3d-a33b-647007ece360
Response  204

Generated by aglio on 15 May 2026