Leads

#The Lead object

Lead: the participation of one contact in one campaign. The same person in two campaigns produces two different leads.

Attributes

• objectstring
  Object type, always lead.
• idstring (uuid)
  Lead ID (participation in a campaign).
• workspace_idstring (uuid)
  Workspace of the campaign.
• campaign_idstring (uuid)
  Campaign the contact participates in.
• usernamestring or null
  Telegram username without @. Can be null. Not unique: use fields.record_id to link to your CRM.
• statusstring
  Lead status in the campaign. Values: new contacted completed replied blocked failed suspended deleted opted_out unknown
• external_idnull
  Reserved for future versions. Always null in v1.
• fieldsobject
  Allowed fields from the contact record.
  Child attributes

  • record_idstring or nullmay be absent
    Record ID in an external CRM, passed when the contacts were uploaded. null if record_id_status is not valid. Up to 128 characters.
  • first_namestring or nullmay be absent
    First name. Up to 1024 characters.
  • last_namestring or nullmay be absent
    Last name. Up to 1024 characters.
  • companystring or nullmay be absent
    Company. Up to 1024 characters.
  • positionstring or nullmay be absent
    Job title. Up to 1024 characters.
  • websitestring or nullmay be absent
    Website. Up to 1024 characters.
  • sourcestring or nullmay be absent
    Contact source. Up to 1024 characters.
  • utm_sourcestring or nullmay be absent
    The utm_source tag. Up to 1024 characters.
  • utm_mediumstring or nullmay be absent
    The utm_medium tag. Up to 1024 characters.
  • utm_campaignstring or nullmay be absent
    The utm_campaign tag. Up to 1024 characters.
• fields_truncatedboolean
  true if some field values were shortened or hidden due to size limits.
• record_id_statusstring
  How reliable fields.record_id is: valid, missing, conflict or unknown. Values: valid missing conflict unknown
• first_contact_accountobject or null
  Account that sent the first message. null if unknown.
  Child attributes

  • idstring (uuid)
    Account ID.
  • usernamestring or null
    Account username without @. Can be null.
  • namestring or null
    Account display name. Can be null.
• first_message_sent_atstring (date-time) or null
  When the first message was sent. null if sending is not confirmed.
• first_reply_atstring (date-time) or null
  When the first reply arrived. null if there was no reply.
• delivery_statestring
  Delivery state of the next or most recent message in the sequence. Values: waiting_queue queued held sent failed unknown
• automation_statestring
  State of the automatic sequence for this lead. Leads without a scheduled message, such as those who replied, currently often have unknown. Values: running paused held stopped completed unknown
• reasonobject
  Why the sequence is waiting, if known.
  Child attributes

  • reason_codestring
    Reason code. Values: none schedule_window daily_limit queue_pending telegram_wait account_unavailable account_restricted campaign_paused subscription_inactive manual_hold automation_stopped service_unavailable unknown
  • reason_observed_atstring (date-time) or null
    When the reason was recorded. null if unknown.
  • next_attempt_atstring (date-time) or null
    When the next attempt is expected. null if the time is unknown.
  • requires_customer_actionboolean or null
    Whether someone needs to act in Meliora for sending to resume. null if unknown.
• created_atstring (date-time)
  When the contact was added to the campaign.
• observed_atstring (date-time)
  Time the server read the data.

#List leads

GET/v1/leads

Leads (contacts' participation in campaigns) in the key's scope, oldest first by created_at.

Permission

leads:read

Request weight

2

Parameters

• limitinteger, queryoptional
  Number of objects to return per page. From 1 to 100. Defaults to 50.
• cursorstring, queryoptional
  The next_cursor value from the previous response. Other filters must match the first request.
• workspace_idstring (uuid), queryoptional
  Only objects in this workspace.
• campaign_idstring (uuid), queryoptional
  Only objects in this campaign.
• usernamestring, queryoptional
  Exact Telegram username. A leading @ and letter case are ignored.
• statusstring, queryoptional
  Only leads with this status. Values: new contacted completed replied blocked failed suspended deleted opted_out unknown
• delivery_statestring, queryoptional
  Only leads with this delivery state. The values waiting_queue and failed are not returned at the moment, so filtering by them returns an empty list. Values: waiting_queue queued held sent failed unknown

Response

A list: object, data (an array of Lead objects), has_more, next_cursor. See Pagination.

Endpoint-specific errors

• cursor_mismatch: The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
• scope_required: The key does not have permission for this read. Texts also require "Message text" to be enabled.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.
• cursor_expired: The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors are described in Errors.

#Retrieve a lead

GET/v1/leads/{id}

A single lead by ID. A lead outside the key's scope returns 404.

Permission

leads:read

Request weight

1

Parameters

• idstring (uuid), pathrequired
  Lead ID.

Response

Returns a Lead object.

Endpoint-specific errors

• scope_required: The key does not have permission for this read. Texts also require "Message text" to be enabled.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.

Common errors are described in Errors.