Preview an import

POST/v1/organization/{orgId}/crm/import/preview

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

What an import would do, without doing it: how many rows are new, already contacts or invalid (with the line and reason), emails repeated in the file, and up to 200 rows as they would be saved. Writes nothing, so read:crm is enough. Requires read:crm. Refused for a key restricted to particular events. Also at POST /v1/org/{orgId}/crm/import/preview, and at POST /v1/crm/import/preview with the organization taken from the token.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "rows": [
    {
      "email": "jane@example.com",
      "first_name": "<string>",
      "last_name": "<string>",
      "name": "<string>",
      "company": "<string>",
      "title": "<string>",
      "types": [
        "speaker"
      ],
      "tags": [
        "<string>"
      ]
    }
  ],
  "csv": "<string>",
  "mapping": {
    "key": "<string>"
  },
  "types": [
    "speaker"
  ],
  "tagIds": [
    "<string>"
  ]
}'

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "rows": [
      {
        "email": "jane@example.com",
        "first_name": "<string>",
        "last_name": "<string>",
        "name": "<string>",
        "company": "<string>",
        "title": "<string>",
        "types": [
          "speaker"
        ],
        "tags": [
          "<string>"
        ]
      }
    ],
    "csv": "<string>",
    "mapping": {
      "key": "<string>"
    },
    "types": [
      "speaker"
    ],
    "tagIds": [
      "<string>"
    ]
  }),
});

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

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "rows": [
            {
                "email": "jane@example.com",
                "first_name": "<string>",
                "last_name": "<string>",
                "name": "<string>",
                "company": "<string>",
                "title": "<string>",
                "types": [
                    "speaker"
                ],
                "tags": [
                    "<string>"
                ]
            }
        ],
        "csv": "<string>",
        "mapping": {
            "key": "<string>"
        },
        "types": [
            "speaker"
        ],
        "tagIds": [
            "<string>"
        ]
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "rows": [
    {
      "email": "jane@example.com",
      "first_name": "<string>",
      "last_name": "<string>",
      "name": "<string>",
      "company": "<string>",
      "title": "<string>",
      "types": [
        "speaker"
      ],
      "tags": [
        "<string>"
      ]
    }
  ],
  "csv": "<string>",
  "mapping": {
    "key": "<string>"
  },
  "types": [
    "speaker"
  ],
  "tagIds": [
    "<string>"
  ]
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

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

echo $response;

package main

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

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview", strings.NewReader(`{
  "rows": [
    {
      "email": "jane@example.com",
      "first_name": "<string>",
      "last_name": "<string>",
      "name": "<string>",
      "company": "<string>",
      "title": "<string>",
      "types": [
        "speaker"
      ],
      "tags": [
        "<string>"
      ]
    }
  ],
  "csv": "<string>",
  "mapping": {
    "key": "<string>"
  },
  "types": [
    "speaker"
  ],
  "tagIds": [
    "<string>"
  ]
}`))
  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))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/crm/import/preview"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"rows\": [\n    {\n      \"email\": \"jane@example.com\",\n      \"first_name\": \"<string>\",\n      \"last_name\": \"<string>\",\n      \"name\": \"<string>\",\n      \"company\": \"<string>\",\n      \"title\": \"<string>\",\n      \"types\": [\n        \"speaker\"\n      ],\n      \"tags\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"csv\": \"<string>\",\n  \"mapping\": {\n    \"key\": \"<string>\"\n  },\n  \"types\": [\n    \"speaker\"\n  ],\n  \"tagIds\": [\n    \"<string>\"\n  ]\n}"))
    .build();

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

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

Try it

Region

Authorization

Send as

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

POST

Response headers

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

Send rows or csv.

rowsCrmImportRowInput | CrmImportCompanyRowInput[]
People rows (target people, the default) or company rows (target companies).
Max items
250
Option 1 (CrmImportRowInput)
A row in the import's field keys (the same keys a preview or discovery returns, so its rows can be sent back unchanged).
- emailstring<email>required
- first_namestring
- last_namestring
- namestring
  A full name, instead of first and last.
- companystring
- titlestring
- typesstring[]
  Allowed values
  "speaker", "sme", "influencer", "exhibitor", "sponsor"
- tagsstring[]
  Tag names.
Option 2 (CrmImportCompanyRowInput)
A company row, sent with target companies. Matched by name; tags mark it a sponsor, an exhibitor or both.
- namestringrequired
- websitestring
- tagsstring[]
  Allowed values
  "sponsor", "exhibitor"
  Max items
  2
csvstring
CSV text with a header row (up to 250 rows on POST …/crm/import).
mappingobject
Column → field (email, first_name, last_name, name, company, title, types, tags), as import/parse suggests. Optional with rows.
typesstring[]
Given to every row.
Allowed values
"speaker", "sme", "influencer", "exhibitor", "sponsor"
tagIdsstring[]
Tags given to every row.

Example

{
  "rows": [
    {
      "email": "jane@example.com",
      "first_name": "<string>",
      "last_name": "<string>",
      "name": "<string>",
      "company": "<string>",
      "title": "<string>",
      "types": [
        "speaker"
      ],
      "tags": [
        "<string>"
      ]
    }
  ],
  "csv": "<string>",
  "mapping": {
    "key": "<string>"
  },
  "types": [
    "speaker"
  ],
  "tagIds": [
    "<string>"
  ]
}

Responses

200`application/json`

successboolean
payloadobject
Show child attributes
- totalinteger
- newinteger
- existinginteger
- invalidCrmInvalidRow[]
  Show child attributes
  - lineinteger
  - reasonstring
- duplicates_in_fileinteger
- rowsCrmImportRow[]
  Max items
  200
  Show child attributes
  - emailstring
  - first_namestring | null
  - last_namestring | null
  - companystring | null
  - titlestring | null
  - typesstring[]
    Allowed values
    "speaker", "sme", "influencer", "exhibitor", "sponsor"
  - statusstring
    Allowed values
    "new", "existing", "invalid"
  - contact_idstring | null
    With existing: the contact the row matches.
  - reasonstring | null
    With invalid: why.

401

Missing, invalid or expired token.

403`application/json`

SCOPE_REQUIRED: the token lacks read:crm.
ORG_WIDE_TOKEN_REQUIRED: the key is restricted to particular events; use a key without an event restriction.
FORBIDDEN: the token's user cannot read the organization's contacts.

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

404`application/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

{
  "success": true,
  "payload": {
    "total": 123,
    "new": 123,
    "existing": 123,
    "invalid": [
      {
        "line": 123,
        "reason": "<string>"
      }
    ],
    "duplicates_in_file": 123,
    "rows": [
      {
        "email": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "company": "<string>",
        "title": "<string>",
        "types": [
          "speaker"
        ],
        "status": "new",
        "contact_id": "<string>",
        "reason": "<string>"
      }
    ]
  }
}

{
  "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>"
    }
  }
}

{
  "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>"
    }
  }
}

Preview an import

Request example

Try it

Authorizations

Path parameters

Request body

Responses

200application/json

401

403application/json

404application/json

429

Response examples

200`application/json`

403`application/json`

404`application/json`