Sign In

Contacts

One contact can be reached on several channels. Each phone number or email address belongs to exactly one contact.

List contacts

Search with search (name, phone, email). Page with limit (max 100) and before (an ISO date from the last item).

Scopecontact:read
searchstring
app.docs.v1.contact.list.params.search
limitnumber
app.docs.v1.contact.list.params.limit
beforeISO date
app.docs.v1.contact.list.params.before
GEThttps://www.beamvia.com/api/v1/contact
Search
curl -X GET "https://www.beamvia.com/api/v1/contact?search=rina" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "contacts": [
      {
        "id": "6650f0c2a1b2c3d4e5f60690",
        "name": "Rina",
        "avatar": {
          "url": null
        },
        "phone": "+6281234567890",
        "email": "[email protected]",
        "identities": [
          {
            "type": "WHATSAPP",
            "jid": "[email protected]",
            "phone": "+6281234567890"
          },
          {
            "type": "EMAIL",
            "address": "[email protected]"
          }
        ],
        "attributes": {
          "plan": "gold"
        },
        "tagIds": [],
        "notes": "",
        "lastSeenAt": "2026-10-20T08:00:00.000Z",
        "createdAt": "2026-10-01T09:00:00.000Z"
      }
    ]
  }
}

Create a contact

Pass one or more identities. Returns the existing contact when the first identity is already known.

Scopecontact:write
namestring | null
app.docs.v1.contact.create.params.name
identitiesarrayrequired
app.docs.v1.contact.create.params.identities
attributesobject
app.docs.v1.contact.create.params.attributes
POSThttps://www.beamvia.com/api/v1/contact
Create
curl -X POST "https://www.beamvia.com/api/v1/contact" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rina",
    "identities": [
      {
        "type": "WHATSAPP",
        "phone": "+6281234567890"
      },
      {
        "type": "EMAIL",
        "address": "[email protected]"
      }
    ],
    "attributes": {
      "plan": "gold"
    }
  }'
{
  "status": true,
  "message": "OK",
  "data": {
    "contact": {
      "id": "6650f0c2a1b2c3d4e5f60690",
      "name": "Rina",
      "avatar": {
        "url": null
      },
      "phone": "+6281234567890",
      "email": "[email protected]",
      "identities": [
        {
          "type": "WHATSAPP",
          "jid": "[email protected]",
          "phone": "+6281234567890"
        },
        {
          "type": "EMAIL",
          "address": "[email protected]"
        }
      ],
      "attributes": {
        "plan": "gold"
      },
      "tagIds": [],
      "notes": "",
      "lastSeenAt": "2026-10-20T08:00:00.000Z",
      "createdAt": "2026-10-01T09:00:00.000Z"
    }
  }
}

Update a contact

Change name, notes and attributes. Attributes are replaced as a whole.

Scopecontact:write
namestring | null
app.docs.v1.contact.update.params.name
notesstring
app.docs.v1.contact.update.params.notes
attributesobject
app.docs.v1.contact.update.params.attributes
PATCHhttps://www.beamvia.com/api/v1/contact/:contactId
Update
curl -X PATCH "https://www.beamvia.com/api/v1/contact/6650f0c2a1b2c3d4e5f60690" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "plan": "platinum",
      "coupon": ""
    }
  }'
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "contact": {
      "id": "6650f0c2a1b2c3d4e5f60690",
      "name": "Rina",
      "avatar": {
        "url": null
      },
      "phone": "+6281234567890",
      "email": "[email protected]",
      "identities": [
        {
          "type": "WHATSAPP",
          "jid": "[email protected]",
          "phone": "+6281234567890"
        },
        {
          "type": "EMAIL",
          "address": "[email protected]"
        }
      ],
      "attributes": {
        "plan": "platinum"
      },
      "tagIds": [],
      "notes": "",
      "lastSeenAt": "2026-10-20T08:00:00.000Z",
      "createdAt": "2026-10-01T09:00:00.000Z"
    }
  }
}