vamo
Book a demo
API reference navigation
POST /v1/shortlists/{id}/members

Add shortlist members

Access
Authenticated
shortlist:update
Cost
Free
Rate limit
30 / minute per account
Quota
None

Add live contacts to a shortlist (idempotent). The shortlist must not be archived.

Path parameters

  • id string required
    max 16 chars

Request body AddMembersRequest

  • contactIds array of string required

    The contacts to add, 1 to 500 at a time. Adding one that is already on the list is not an error.

    min 1 items, max 500 items
  • source object

    Provenance to record on each membership created by this call.

    • kind string required

      How these contacts came to be on the list.

      searchfeedimportmanualmanagedapi
    • ref string

      The subject behind `kind`, for example the agent or saved search that produced them.

      max 200 chars
  • matchReasons object

    Per-contact free-text reason for the match, keyed by contact id, stored on the membership. Contacts you omit simply carry none.

  • bestRepo object

    Per-contact `owner/repo` to use as the outreach anchor (the repository an email refers to), keyed by contact id. For any contact you omit, the anchor is resolved server-side from their top-starred repository, or left empty if there is none.

Responses

  • 200 Add result
    • added array of string required

      Contacts newly added to the list by this call.

    • existing array of string required

      Contacts that were already on the list and were left alone.

  • 401 No or invalid credential
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at the credit top-up).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailbox
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 403 Missing shortlist:update
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at the credit top-up).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailbox
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 404 Shortlist or one or more contacts unknown
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at the credit top-up).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailbox
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 409 Shortlist archived
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at the credit top-up).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailbox
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

vamo
PricingLearning CenterBook a demoChangelogPrivacyTerms

© 2026 Vamo Holdings, Inc.