---
title: "Get campaign by ID"
method: GET
path: "/v1/projects/{project_id}/campaigns/{id}"
tags: ["Campaign"]
---

# Get campaign by ID

`GET /v1/projects/{project_id}/campaigns/{id}`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/campaigns/{id}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Retrieves the campaign with the given ID.

## Path parameters

- `project_id` string, required
- `id` string, required

## Response `200`

Successful response

- Campaign: A campaign is something that is sent to a group of contacts on a particular schedule. Depending on the campaign type, a campaign may send a text message, make a voice call, or trigger an automated service. A campaign may either send a single broadcast at once, or send multiple broadcasts to different contacts over time. Campaigns are initially created as a draft and can be edited and previewed before being sent. This supports a workflow where campaigns can be drafted via the API, and subsequently edited, approved, and sent via either the web app or the API. Once sent, a campaign creates one or more broadcasts to deliver messages to the target recipients. Campaigns build on top of other core entity types including broadcasts and scheduled messages. Although it is possible to send broadcasts or schedule messages directly via the API, campaigns can be used in order to provide the ability to save drafts, allow manual editing and approval before sending, or to organize broadcasts within Telerivet.
  - `id` string: ID of the campaign
  - `name` string: Name of the campaign, which must be unique within the project. The campaign name is only visible within Telerivet, and does not appear in the messages sent to contacts.
  - `campaign_type` 'broadcast_text' | 'broadcast_call' | 'broadcast_svc' | 'relative' | 'anniversary': Type of the campaign. The following campaign types are available: - `broadcast_text` - Send a text message to a group of contacts - `broadcast_call` - Send a voice call to a group of contacts - `broadcast_svc` - Trigger a service for a group of contacts - `relative` - Send a series of messages over time relative to when each contact was added to a group - `anniversary` - Send messages on recurring dates (e.g. birthdays, anniversaries)
  - `status` 'draft' | 'scheduled' | 'sent' | 'pending_review': Current status of the campaign
  - `group_id` string: ID of the group of contacts that the campaign will be sent to
  - `exclude_group_id` string, nullable: ID of a group of contacts to exclude from the campaign
  - `route_id` string: ID of the phone or route used to send the campaign
  - `broadcast_id` string, nullable: ID of the most recent broadcast created by this campaign, if applicable
  - `estimated_count` integer, nullable: Estimated number of messages that will be sent in this campaign
  - `message_count` integer, nullable: Number of messages that have been sent in this campaign
  - `respondent_group_id` string, nullable: ID of a group to add contacts to after they respond to the campaign
  - `clicked_group_id` string, nullable: ID of a group to add contacts to after they click a link in the campaign
  - `label_ids` string: List of IDs of labels applied to messages sent by this campaign
  - `solution_id` string, nullable: ID of the solution that this campaign belongs to, if any
  - `schedule_mode` 'immediate' | 'at_time', nullable: Indicates whether the campaign should be sent immediately or at a future time (applies to broadcast campaign types). If `schedule_time` is set, `schedule_mode` is automatically set to `at_time`. If `schedule_mode` is set to `immediate` or `null`, `schedule_time` is automatically cleared. Note that after setting schedule_mode to "immediate" on a campaign with the `draft` status, the campaign will not actually be sent until the API method is called to send the campaign.
  - `schedule_time` integer, nullable: The time to send the campaign, as a UNIX timestamp (applies to broadcast campaign types). Setting this to a non-null value automatically sets `schedule_mode` to `at_time`. Note that after setting schedule_time on a campaign with the `draft` status, the campaign will not actually be scheduled until the API method is called to schedule the campaign.
  - `content` string, nullable: Text content of the message (applies to `broadcast_text` campaigns), or the text-to-speech text for voice calls (applies to `broadcast_call` campaigns). May contain variables like `[[contact.name]]`. (See available variables)
  - `media` object[], nullable: Array of media attachments (applies to `broadcast_text` campaigns).
    - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
    - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
    - `filename` string: Original filename
    - `size` integer: File size in bytes
    - `file_id` string: ID of the stored file, if applicable
  - `route_params` object, nullable: Route-specific parameters for the message (applies to `broadcast_text` campaigns). See Route-Specific Parameters.
  - `variants` object[], nullable: Alternative message bodies (applies to `broadcast_text` campaigns). Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `track_clicks` boolean: Whether to shorten links and track link clicks (applies to `broadcast_text` campaigns).
  - `short_link_params` object, nullable: Parameters for short links when `track_clicks` is enabled (applies to `broadcast_text` campaigns).
    - `domain` string: Custom domain for short links. Must be configured for this project.
    - `expiration_sec` integer: Expiration time in seconds for short links.
  - `audio_url` string, nullable: For voice calls, the URL of an MP3 file to play when the contact answers the call (applies to `broadcast_call` campaigns)
  - `tts_lang` 'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE': For voice calls, the language of the text-to-speech voice (applies to `broadcast_call` campaigns)
  - `tts_voice` 'female' | 'male': For voice calls, the text-to-speech voice (applies to `broadcast_call` campaigns)
  - `service_id` string, nullable: ID of the service associated with this campaign (applies to `broadcast_call` or `broadcast_svc` campaigns)
  - `date_variable` string, nullable: Custom contact variable storing date or date/time values relative to which messages will be scheduled (`relative` and `anniversary` campaigns only). To send messages relative to when each contact signs up or joins the group, use a date/time field that is set automatically when contacts are added to the campaign's group (the group's `add_time_variable`), and schedule the first message with a minute offset (`offset_scale` `I`) so that it is sent shortly after the contact joins, rather than at a fixed `time_of_day`. Minute offsets are not supported for date fields without a time.
  - `items` object[], nullable: Array of campaign items (applies to `relative` and `anniversary` campaigns). Each item defines a scheduled message with timing and content.
    - `mode` string: Type of message to send: `"text"`, `"service"`, or `"call"`
    - `offset_count` integer: The number of minutes/days/weeks/months/years (according to `offset_scale`) to adjust the time of the scheduled message relative to the date or date/time stored in the contact variable. May be positive (after), negative (before), or zero (on the date).
    - `offset_scale` string: The type of interval for the offset (I=minutes, D=day, W=week, M=month, Y=year). With `I` (minutes), the message is sent at the exact date/time stored in the contact variable plus the offset, and `time_of_day` is ignored; this requires `date_variable` to be a date/time field (not a date field). With `D`, `W`, `M`, or `Y`, the message is sent at `time_of_day` on the adjusted date.
    - `time_of_day` string: Time of day when messages will be sent, in HH:MM format (with hours from 00 to 23). Ignored when `offset_scale` is `I`. Messages are only scheduled for future times: if the scheduled time has already passed when the contact's date is set (e.g. `offset_count` 0 with `time_of_day` 09:00 for a contact added to the group at 14:00), that message is skipped for the contact. To send a message on the same day a contact joins, use a minute offset instead.
    - `content` string: Text content of the message (when `mode` is `"text"`), or the text-to-speech text for voice calls (when `mode` is `"call"`). May contain variables like `[[contact.name]]`. [(See available variables)](#variables)
    - `media` object[]: Array of media attachments (when `mode` is `"text"`).
      - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
      - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
      - `filename` string: Original filename
      - `size` integer: File size in bytes
      - `file_id` string: ID of the stored file, if applicable
    - `route_params` object: Route-specific parameters for the message (when `mode` is `"text"`). See [Route-Specific Parameters](#route_params).
    - `variants` string[]: Alternative message bodies used instead of the default message body when their conditions match (when `mode` is `"text"`). See the `variants` parameter of [sendMessage](#Project.sendMessage).
    - `track_clicks` boolean: Whether to shorten links and track link clicks (when `mode` is `"text"`).
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (when `mode` is `"text"`).
      - `domain` string: Custom domain for short links. Must be configured for this project.
      - `expiration_sec` integer: Expiration time in seconds for short links.
    - `service_id` string: ID of the service to trigger (when `mode` is `"service"` or `"call"`)
    - `audio_url` string: URL of an MP3 file to play for voice calls (when `mode` is `"call"`)
    - `tts_lang` string: Language for text-to-speech voice calls (when `mode` is `"call"`)
    - `tts_voice` string: Voice for text-to-speech voice calls (when `mode` is `"call"`)
  - `message_type` string, nullable: Type of messages sent by this campaign, or null if not applicable
  - `timezone_id` string, nullable: The ID of the timezone used for scheduling messages in this campaign, or null to use the project's default timezone
  - `time_created` integer: Time the campaign was created in Telerivet
  - `time_updated` integer: Time the campaign was last updated in Telerivet
  - `vars` object: Custom variables stored for this campaign. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `url` string: URL to view the campaign in the Telerivet web app
  - `url_edit` string: URL to edit the campaign in the Telerivet web app
  - `url_send` string: URL to preview and send the campaign in the Telerivet web app
  - `user_id` string: ID of the Telerivet user who created the campaign
  - `project_id` string: ID of the project this campaign belongs to

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)