Skip to content
spirby spirby docs

List contacts in the workspace, optionally filtered/searched

GET
/v1/contacts
 
curl --request GET \
  --url 'https://api.spirby.com/v1/contacts?sort=created' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
cursor
string
>= 1 characters
limit
integer
>= 1 <= 100
sort
string
Allowed values: created last_seen mrr
plan
Any of:
string
q
string
>= 1 characters <= 200 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful response

Media type application/json
object
data
required
Array<object>

A contact list item: row plus a per-row post count.

object
consentBasis
required

Lawful basis the row was created under. sdk_identify = your app already had consent; public_interaction_opt_in = end-user ticked the opt-in box; admin_created = workspace admin attested; legacy_inferred = pre-opt-in backfill (treat as suppressed for marketing, DSAR-eligible).

string
Allowed values: sdk_identify public_interaction_opt_in admin_created legacy_inferred
createdAt
required
string format: date-time
currency
required
string | null
email
required
string | null
externalUserId
required
string | null
firstSeenAt
required
string format: date-time
id
required
string
lastSeenAt
required
string format: date-time
metadata
required
object
key
additional properties
mrrCents
required
integer | null
name
required
string | null
organizationId
required
string
plan
required
string | null
postCount
required
integer
source
required

How this contact row entered the system. identify = SDK widget / REST identify; admin = manual create; public_* = end-user opted in on the public board.

string
Allowed values: identify admin public_post public_vote public_comment
updatedAt
required
string format: date-time
nextCursor
required
string | null
Example 
{
  "data": [
    {
      "consentBasis": "sdk_identify",
      "source": "identify"
    }
  ]
}

401

Section titled “401 ”

Missing or invalid API key

Media type application/json
object
error
required
object
code
required
string
details
object
key
additional properties
message
required
string
Example generated
{
  "error": {
    "code": "example",
    "details": {
      "additionalProperty": "example"
    },
    "message": "example"
  }
}

403

Section titled “403 ”

Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)

Media type application/json
object
error
required
object
code
required
string
details
object
key
additional properties
message
required
string
Example generated
{
  "error": {
    "code": "example",
    "details": {
      "additionalProperty": "example"
    },
    "message": "example"
  }
}

422

Section titled “422 ”

Validation failed

Media type application/json
object
error
required
object
code
required
string
details
object
key
additional properties
message
required
string
Example generated
{
  "error": {
    "code": "example",
    "details": {
      "additionalProperty": "example"
    },
    "message": "example"
  }
}

429

Section titled “429 ”

Rate limit exceeded

Media type application/json
object
error
required
object
code
required
string
details
object
key
additional properties
message
required
string
Example generated
{
  "error": {
    "code": "example",
    "details": {
      "additionalProperty": "example"
    },
    "message": "example"
  }
}

500

Section titled “500 ”

Internal error

Media type application/json
object
error
required
object
code
required
string
details
object
key
additional properties
message
required
string
Example generated
{
  "error": {
    "code": "example",
    "details": {
      "additionalProperty": "example"
    },
    "message": "example"
  }
}