Add people to contacts

POST/v1/organization/{orgId}/crm/people/add-to-contacts

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Creates a contact for each person without one (a contact already holding the email is linked instead) and links the person to it. The two stay separate records. Emails no one. Requires write:crm. Refused for a key restricted to particular events. Also at POST /v1/org/{orgId}/crm/people/add-to-contacts, and at POST /v1/crm/people/add-to-contacts with the organization taken from the token.

Request example

cURL

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "keys": [
    "<string>"
  ],
  "types": [
    "speaker"
  ]
}'

JavaScript

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "keys": [
      "<string>"
    ],
    "types": [
      "speaker"
    ]
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "keys": [
            "<string>"
        ],
        "types": [
            "speaker"
        ]
    },
)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "keys": [
    "<string>"
  ],
  "types": [
    "speaker"
  ]
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts", strings.NewReader(`{
  "keys": [
    "<string>"
  ],
  "types": [
    "speaker"
  ]
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/crm/people/add-to-contacts"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"keys\": [\n    \"<string>\"\n  ],\n  \"types\": [\n    \"speaker\"\n  ]\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

RegionUS Region — https://public-api.sessionboard.comEU Region — https://public-api-eu.sessionboard.com

Authorization

Send asAPI token (x-access-token)OAuth access token (Bearer)

Token

Your token stays in this page. It is sent only to the region above and is never saved; it is gone when you leave or reload the page.

Path parameters

orgId*

Body application/json

{ "keys": [ "<string>" ], "types": [ "speaker" ] }

POST

Send request

Authorizations

• x-access-tokenstringheader

  Organization API token. Generate from Organization Settings → API Tokens.

• AuthorizationBearer <token>headeror

  OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

• orgIdstringpathrequired

  Your organization ID. Any other organization returns 404.

Request body

application/jsonrequired

• keysstring[]required

  Person keys from GET …/crm/people.

  Min items

  1

  Max items

  200

• typesstring[]

  Types for the new contacts.

  Allowed values

  "speaker", "sme", "influencer", "exhibitor", "sponsor"

Example

{
  "keys": [
    "<string>"
  ],
  "types": [
    "speaker"
  ]
}

Responses

200application/json

OK

• successboolean
• payloadobject
  Show child attributes

  • createdinteger
  • linkedinteger

400application/json

VALIDATION_ERROR: the body or a path id does not match the schema.

• successboolean
• errorstring

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• codestring

  A more specific reason: exists, read_only, platform_customer.

• messagestringrequired
• contactCrmContact

  With code: exists: the contact that has the email.

  Show child attributes

  • idstring
  • first_namestring
  • last_namestring | null
  • namestring
  • emailstring<email>
  • companystring | null
  • titlestring | null

    Job title.

  • avatar_urlstring | null
  • typesstring[]

    Allowed values

    "speaker", "sme", "influencer", "exhibitor", "sponsor"

  • tagsCrmTag[]
    Show child attributes

    • idstring
    • namestring
  • events_countinteger
  • sessions_countinteger
  • last_activity_atstring<date-time> | null
  • activeboolean

    An active contact in the last 365 days.

  • sourcestring | null

    Where the contact came from.

  • created_atstring<date-time>
  • hrefstring

    The contact in Sessionboard CRM.

  • stageobject | null

    The contact's pipeline stage; null when not in the pipeline.

    Show child attributes

    • idstring
    • labelstring

401

Missing, invalid or expired token.

403application/json

• SCOPE_REQUIRED: the token lacks write:crm (or read:crm for the POSTs that only read).
• ORG_WIDE_TOKEN_REQUIRED: the key is restricted to particular events.
• code: plan_read_only (or read_only): the CRM trial or plan has ended; everything can still be read.
• code: platform_customer: the organization works with Sessionboard on a platform contract, so its contacts are in the Sessionboard platform.
• code: FEATURE_NOT_ENABLED: contracts are not turned on for the organization (contracts operations only).
• FORBIDDEN with no code: the token's user lacks the Contacts permission the change needs (connecting and disconnecting apps need an organization admin).

• successboolean
• errorstring

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• codestring

  A more specific reason: exists, read_only, platform_customer.

• messagestringrequired
• contactCrmContact

  With code: exists: the contact that has the email.

  Show child attributes

  • idstring
  • first_namestring
  • last_namestring | null
  • namestring
  • emailstring<email>
  • companystring | null
  • titlestring | null

    Job title.

  • avatar_urlstring | null
  • typesstring[]

    Allowed values

    "speaker", "sme", "influencer", "exhibitor", "sponsor"

  • tagsCrmTag[]
    Show child attributes

    • idstring
    • namestring
  • events_countinteger
  • sessions_countinteger
  • last_activity_atstring<date-time> | null
  • activeboolean

    An active contact in the last 365 days.

  • sourcestring | null

    Where the contact came from.

  • created_atstring<date-time>
  • hrefstring

    The contact in Sessionboard CRM.

  • stageobject | null

    The contact's pipeline stage; null when not in the pipeline.

    Show child attributes

    • idstring
    • labelstring

404application/json

NOT_FOUND: orgId is not the token's organization, or the contact, tag or app is not in it.

• successboolean
• errorstring

  Allowed values

  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"

• codestring

  A more specific reason: exists, read_only, platform_customer.

• messagestringrequired
• contactCrmContact

  With code: exists: the contact that has the email.

  Show child attributes

  • idstring
  • first_namestring
  • last_namestring | null
  • namestring
  • emailstring<email>
  • companystring | null
  • titlestring | null

    Job title.

  • avatar_urlstring | null
  • typesstring[]

    Allowed values

    "speaker", "sme", "influencer", "exhibitor", "sponsor"

  • tagsCrmTag[]
    Show child attributes

    • idstring
    • namestring
  • events_countinteger
  • sessions_countinteger
  • last_activity_atstring<date-time> | null
  • activeboolean

    An active contact in the last 365 days.

  • sourcestring | null

    Where the contact came from.

  • created_atstring<date-time>
  • hrefstring

    The contact in Sessionboard CRM.

  • stageobject | null

    The contact's pipeline stage; null when not in the pipeline.

    Show child attributes

    • idstring
    • labelstring

429

The token's request limit (100 requests per 15 minutes by default) or, for writes, its daily write quota. Wait Retry-After seconds.

• Retry-Afterintegerheader

  Seconds to wait before retrying.

Response examples

200

{
  "success": true,
  "payload": {
    "created": 123,
    "linked": 123
  }
}

400

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "code": "<string>",
  "message": "<string>",
  "contact": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "name": "<string>",
    "email": "jane@example.com",
    "company": "<string>",
    "title": "<string>",
    "avatar_url": "<string>",
    "types": [
      "speaker"
    ],
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "events_count": 123,
    "sessions_count": 123,
    "last_activity_at": "2026-01-15T09:30:00Z",
    "active": true,
    "source": "<string>",
    "created_at": "2026-01-15T09:30:00Z",
    "href": "<string>",
    "stage": {
      "id": "<string>",
      "label": "<string>"
    }
  }
}

403

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "code": "<string>",
  "message": "<string>",
  "contact": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "name": "<string>",
    "email": "jane@example.com",
    "company": "<string>",
    "title": "<string>",
    "avatar_url": "<string>",
    "types": [
      "speaker"
    ],
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "events_count": 123,
    "sessions_count": 123,
    "last_activity_at": "2026-01-15T09:30:00Z",
    "active": true,
    "source": "<string>",
    "created_at": "2026-01-15T09:30:00Z",
    "href": "<string>",
    "stage": {
      "id": "<string>",
      "label": "<string>"
    }
  }
}

404

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "code": "<string>",
  "message": "<string>",
  "contact": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "name": "<string>",
    "email": "jane@example.com",
    "company": "<string>",
    "title": "<string>",
    "avatar_url": "<string>",
    "types": [
      "speaker"
    ],
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "events_count": 123,
    "sessions_count": 123,
    "last_activity_at": "2026-01-15T09:30:00Z",
    "active": true,
    "source": "<string>",
    "created_at": "2026-01-15T09:30:00Z",
    "href": "<string>",
    "stage": {
      "id": "<string>",
      "label": "<string>"
    }
  }
}