Query contacts

Use the query endpoint to select contact properties, filter records, and read additional pages. This guide uses curl so it does not assume an SDK method.

Prerequisites

You need:

• a Micro API key from Micro settings;
• the UUID of a disposable workspace you can access; and
• permission to read contacts in that workspace.

Keep the key in an environment variable and do not commit it. The public API host is https://developers.micro.so; api.micro.so is the app backend and does not accept this API-key flow.

export MICRO_API_KEY="replace-with-your-api-key"
export MICRO_TEAM_ID="00000000-0000-4000-8000-000000000000"

Send the request

This request returns at most 10 contacts and selects only full_name and email. It does not change workspace data.

curl --request POST \
  "https://developers.micro.so/v2/prism/${MICRO_TEAM_ID}/contact/query" \
  --header "content-type: application/json" \
  --header "x-api-key: ${MICRO_API_KEY}" \
  --data '{
    "query": {
      "select": ["full_name", "email"],
      "limit": 10
    }
  }'

A successful response has this shape. id is always returned at the top level, even when it is not included in select.

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "properties": {
        "full_name": "Sarah Chen",
        "email": "sarah@example.com"
      },
      "is_user_object": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Read the next page

When has_more is true, pass next_cursor back unchanged as query.cursor. Do not parse it. The current cursor is offset-based and can drift when records are added or removed during a multi-page read.

curl --request POST \
  "https://developers.micro.so/v2/prism/${MICRO_TEAM_ID}/contact/query" \
  --header "content-type: application/json" \
  --header "x-api-key: ${MICRO_API_KEY}" \
  --data '{
    "query": {
      "select": ["full_name", "email"],
      "cursor": "replace-with-next-cursor"
    }
  }'

Stop when has_more is false. next_cursor is then null. The maximum page size is 50; larger limits are rejected.

Recover from errors

• 400: check the object type, selected property slugs, filters, and page limit.
• 401: make sure x-api-key is present and the key is valid.
• 403: check the API key and confirm it can access this workspace.
• 500: retry with backoff. Include the response's x-request-id if you contact support.

See the query endpoint reference for all request fields, response schemas, and error definitions included in this pilot.