---
title: "Send a contact card"
method: POST
path: "/contact-cards"
tags: ["Messages"]
---

# Send a contact card

`POST /contact-cards`

## Request

- Base URL: `https://osis.co/api/v1/comms`
- URL: `https://osis.co/api/v1/comms/contact-cards`
- Auth: HTTP bearer

Text someone a contact card they can save, over iMessage or SMS. Pass agent_id to send an agent's card, or name and phone for anyone else. Scope: comms_send.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `to` string, required: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string, required: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string, required: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string, required: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string, required: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string, required: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string, required: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string, required: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string, required: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string, required: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string, required: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string, required: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.
  - object
    - `to` string: Phone number to send to. Required unless you set contact_id or conversation_id. Use E.164, or set default_country for a local number.
    - `contact_id` string: A contact you already have. Required unless you set to or conversation_id.
    - `conversation_id` string, required: A conversation to send in. Required unless you set to or contact_id.
    - `agent_id` string: Send this hosted agent's saved card. Any of name, phone, email, organization, note, or photo you leave out comes from the agent's card.
    - `name` string, required: The name on the card. Required unless you set agent_id. Cut off at 80 characters.
    - `phone` string, required: The phone number on the card, in E.164 format. Required unless you set agent_id.
    - `email` string: An email for the card. With agent_id, defaults to the agent's email.
    - `organization` string: A company name for the card.
    - `note` string: A note for the card.
    - `photo_url` string, uri: An HTTPS link to a JPEG, PNG, or GIF, up to 200,000 bytes.
    - `photo_base64` string: A JPEG, PNG, or GIF as base64 or a data:image/...;base64, URL. Up to 200,000 bytes.
    - `caption` string: Text to send with the card. Leave it out to send just the card.
    - `channel` 'auto' | 'sms' | 'imessage' | 'whatsapp'
    - `default_country` string: Country code, only needed if the number is local and has no country code.
    - `idempotency_key` string: Same as the Idempotency-Key header. If you send both, the header wins.
    - `line_e164` string: For WhatsApp: the number to send from, with WhatsApp turned on. Alias: from.

## Response `200`

Already sent with this idempotency key. Returns the first result.

- SendContactCardResponse
  - `message` Message
    - `id` string
    - `body` string
    - `direction` 'outbound' | 'inbound'
    - `conversation_id` string
    - `reply_to_message_id` string: The ID of the message this replies to, if it's in this conversation.
    - `thread_root_message_id` string: The first message in this thread.
    - `channel` 'sms' | 'imessage' | 'rcs' | 'whatsapp'
    - `status` string
    - `contact_id` string
    - `line_id` string: Line ID when available.
    - `line_e164` string: Your number in this conversation: the number that received the message, or the number you sent from.
    - `to` string
    - `read_at` string, date-time: The native read time when a read receipt is available. For one-to-one iMessage and RCS, the recipient must have read receipts on. Never available for SMS; absence does not mean unread.
    - `created_at` string, date-time
    - `audience` 'direct' | 'shared': Whether the message is in a group conversation or a one-on-one conversation.
    - `author` object: Who sent the message. Display names aren't verified.
      - `contact_id` string, required
      - `external_id` string, required
      - `display_name` string
    - `reply_to_provider_message_id` string: Another ID for the message this replies to, when available.
    - `thread_originator_guid` string: Another ID for the first message in the thread, when available.
    - `attachments` InboundAttachment[]: Files someone sent you. If a message is only files, body is empty.
      - `id` string
      - `filename` string, required
      - `content_type` string, required
      - `mediaType` string, required
      - `size_bytes` integer
      - `transcription` string
      - `url` string, uri: Where to download the file. Needs an API key with comms_read from the same workspace and line.
    - `unsent_at` string, date-time: When the unsend was confirmed. The original text and delivery history are kept.
  - `duplicate` boolean
  - `contact_card` object
    - `name` string
    - `phone` string
    - `agent_id` string

## Other responses

- `201`: Contact card accepted
- `400`: Bad request
- `401`: API key is missing or wrong
- `402`: You've used your plan's messages
- `403`: Your key doesn't have the scope this needs
- `404`: Not found
- `409`: The conversation isn't available, or the request conflicts with an earlier one
- `429`: Too many requests. Slow down and retry.

---

[API](https://skmtc.dev/osis/apis/comms-api.md) · [All operations](https://skmtc.dev/osis/apis/comms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/osis/apis/comms-api/revisions/59a4c0ba8936?raw)