Video Intros · Best for custom applications

Create a Video Intro

POST/v1/video-intros

Use this when your application decides what the Video Intro is: who records it, who it is for, what it says and who delivers it. No touchpoint is involved. It runs through the same creation engine as a touchpoint event.

Authentication

A bearer API key. Authentication.

Headers

Authorizationstringrequired
Bearer followed by your API key. A test key works in the test environment only.
Idempotency-Keystringrequired
A value that is the same every time you send THIS event, and different for every other event.
Content-Typestringrequired
application/json

Request body

memberobjectrequired
The person on your team who records the video. Identify them by any one of these; VideoIntros resolves the member in the organization.
3 fields in member
- idstring
  The member's VideoIntros identifier, from GET /v1/members.
- external_idstring
  Your own identifier for this person, as stored on the member.
- emailstring
  The member's email address. If more than one member has it, the request is refused with member_ambiguous.
recipientobjectrequired
The customer the Video Intro is for.
3 fields in recipient
- first_namestringrequired
  Used in the script and on the page.
- last_namestring
  Optional.
- phonestringrequired
  Mobile number in E.164 form, for example +12405550100.
referenceobject
The record in your system this is about. Stored with the Video Intro and returned on every event, so you can match it back.
3 fields in reference
- sourcestring
  The system the record lives in, for example your_crm.
- typestring
  What kind of record: appointment, job, deal, contact.
- idstring
  Its identifier in that system.
contextobject
What the page says the video is about.
2 fields in context
- titlestring
  The line above the video.
- appointmentobject
  When the moment has a date and time.
  2 fields in appointment
  - starts_atstring
    ISO 8601 date and time.
  - timezonestring
    IANA time zone, for example America/New_York.
instructionsobject
What the member is asked to say.
1 field in instructions
- scriptstring
  The words shown to the member while recording. About 15 seconds.
deliveryobject
Who gets the finished Video Intro to the recipient.
1 field in delivery
- responsibilitystring
  integration (the default): VideoIntros prepares the Video Intro and your system delivers the link. video_intros: VideoIntros sends it to the recipient.
metadataobject
Up to a few of your own key and value pairs. Stored and returned, never interpreted.

Errors

Status	Code	When
401	`unauthorized`	The API key is missing, malformed or revoked.
409	`idempotency_conflict`	This Idempotency-Key was already used with a different body.
422	`validation_failed`	A required field is missing or malformed. The response names the field.
422	`member_not_found`	No active member matches the member you named.
422	`member_ambiguous`	More than one member has that email address. Send the member's id or external_id instead.
429	`rate_limited`	Too many requests. Wait for the time in Retry-After and send again with the same Idempotency-Key.

All errors

Request

curl -X POST https://api.videointros.com/v1/video-intros \
  -H "Authorization: Bearer $VIDEO_INTROS_API_KEY" \
  -H "Idempotency-Key: your_app:order_981:intro" \
  -H "Content-Type: application/json" \
  -d '{
  "member": {
    "email": "[email protected]"
  },
  "recipient": {
    "first_name": "Andrea",
    "last_name": "Smith",
    "phone": "+12405550100"
  },
  "reference": {
    "source": "your_app",
    "type": "order",
    "id": "order_981"
  },
  "context": {
    "title": "Your kitchen consultation",
    "appointment": {
      "starts_at": "2026-10-06T18:00:00Z",
      "timezone": "America/New_York"
    }
  },
  "instructions": {
    "script": "Hi Andrea, I\u0027m Anthony. I\u0027ll be the one coming out tomorrow at 2:00 PM. I wanted you to see a friendly face before I get there."
  },
  "delivery": {
    "responsibility": "integration"
  },
  "metadata": {
    "order_id": "order_981"
  }
}'

const response = await fetch("https://api.videointros.com/v1/video-intros", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDEO_INTROS_API_KEY}`,
    "Idempotency-Key": "your_app:order_981:intro",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "member": {
      "email": "[email protected]"
    },
    "recipient": {
      "first_name": "Andrea",
      "last_name": "Smith",
      "phone": "+12405550100"
    },
    "reference": {
      "source": "your_app",
      "type": "order",
      "id": "order_981"
    },
    "context": {
      "title": "Your kitchen consultation",
      "appointment": {
        "starts_at": "2026-10-06T18:00:00Z",
        "timezone": "America/New_York"
      }
    },
    "instructions": {
      "script": "Hi Andrea, I'm Anthony. I'll be the one coming out tomorrow at 2:00 PM. I wanted you to see a friendly face before I get there."
    },
    "delivery": {
      "responsibility": "integration"
    },
    "metadata": {
      "order_id": "order_981"
    }
  }),
});
const result = await response.json();

import os, requests

response = requests.post(
    "https://api.videointros.com/v1/video-intros",
    headers={
        "Authorization": f"Bearer {os.environ['VIDEO_INTROS_API_KEY']}",
        "Idempotency-Key": "your_app:order_981:intro",
    },
    json={
        "member": {
            "email": "[email protected]",
        },
        "recipient": {
            "first_name": "Andrea",
            "last_name": "Smith",
            "phone": "+12405550100",
        },
        "reference": {
            "source": "your_app",
            "type": "order",
            "id": "order_981",
        },
        "context": {
            "title": "Your kitchen consultation",
            "appointment": {
                "starts_at": "2026-10-06T18:00:00Z",
                "timezone": "America/New_York",
            },
        },
        "instructions": {
            "script": "Hi Andrea, I'm Anthony. I'll be the one coming out tomorrow at 2:00 PM. I wanted you to see a friendly face before I get there.",
        },
        "delivery": {
            "responsibility": "integration",
        },
        "metadata": {
            "order_id": "order_981",
        },
    },
)
result = response.json()

Response · 201

{
  "id": "vi_5b0e7c1e-2a64-4d0f-9b1c-7d2f6a8e9c10",
  "object": "video_intro",
  "status": "requested",
  "touchpoint": null,
  "member": {
    "id": "mem_3f9a1c27",
    "external_id": "rep_456",
    "first_name": "Anthony",
    "last_name": "Baker"
  },
  "recipient": {
    "first_name": "Andrea",
    "last_name": "Smith",
    "phone": "+12405550100"
  },
  "reference": {
    "source": "your_app",
    "type": "order",
    "id": "order_981"
  },
  "delivery": {
    "responsibility": "integration",
    "recipient_url": null
  },
  "metadata": {
    "order_id": "order_981"
  },
  "environment": "test",
  "created_at": "2026-10-05T17:40:01Z"
}

An error

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different body."
  }
}