Move a pipeline entry

PATCH/v1/organization/{orgId}/crm/pipeline/{entryId}

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

Moves the entry to another stage, with an optional note (a note is kept only with a stage move), or changes the event it is for (409 when the contact already has an open entry for that event). Every stage move is kept in the entry's history. Emails no one. Requires write:crm. Refused for a key restricted to particular events. Also at PATCH /v1/org/{orgId}/crm/pipeline/{entryId}, and at PATCH /v1/crm/pipeline/{entryId} with the organization taken from the token.

Request example

curl --request PATCH \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/crm/pipeline/{entryId}' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "stageId": "<string>",
  "note": "<string>",
  "eventId": 123
}'

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/crm/pipeline/{entryId}', {
  method: 'PATCH',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "stageId": "<string>",
    "note": "<string>",
    "eventId": 123
  }),
});

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

import requests

response = requests.request(
    "PATCH",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/pipeline/{entryId}",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "stageId": "<string>",
        "note": "<string>",
        "eventId": 123
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/pipeline/{entryId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => '{
  "stageId": "<string>",
  "note": "<string>",
  "eventId": 123
}',
    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("PATCH", "https://public-api.sessionboard.com/v1/organization/{orgId}/crm/pipeline/{entryId}", strings.NewReader(`{
  "stageId": "<string>",
  "note": "<string>",
  "eventId": 123
}`))
  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/pipeline/{entryId}"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"stageId\": \"<string>\",\n  \"note\": \"<string>\",\n  \"eventId\": 123\n}"))
    .build();

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

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

Try it

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.
entryIdstringpathrequired
The pipeline entry ID.

Request body

application/jsonrequired

stageIdstring
The stage to move to.
notestring
Why; kept with the move.
Max length
2000
eventIdinteger | null
The event the entry is for; null clears it.

Example

{
  "stageId": "<string>",
  "note": "<string>",
  "eventId": 123
}

Responses

200`application/json`

successboolean
payloadCrmPipelineEntry
Show child attributes
- idstring
- contactobject
  Show child attributes
  - idstring
  - namestring
  - emailstring<email>
  - companystring | null
  - titlestring | null
  - typesstring[]
    Allowed values
    "speaker", "sme", "influencer", "exhibitor", "sponsor"
- stageobject
  Show child attributes
  - idstring
  - labelstring
  - categorystring
    Allowed values
    "open", "won", "lost", "nurture"
- eventobject | null
  Show child attributes
  - idinteger
  - namestring
- entered_stage_atstring<date-time>
- last_activity_atstring<date-time> | null
- created_atstring<date-time>
- contracts_countinteger

400`application/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.

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

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

409`application/json`

CONFLICT: the contract is not in a state that allows this (already completed, declined or voided), or the contact already has an open pipeline entry for that event. Nothing was changed.

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": {
    "id": "<string>",
    "contact": {
      "id": "<string>",
      "name": "<string>",
      "email": "jane@example.com",
      "company": "<string>",
      "title": "<string>",
      "types": [
        "speaker"
      ]
    },
    "stage": {
      "id": "<string>",
      "label": "<string>",
      "category": "open"
    },
    "event": {
      "id": 123,
      "name": "<string>"
    },
    "entered_stage_at": "2026-01-15T09:30:00Z",
    "last_activity_at": "2026-01-15T09:30:00Z",
    "created_at": "2026-01-15T09:30:00Z",
    "contracts_count": 123
  }
}

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

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