API Reference

The Jump EHR API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes and authentication.

Base URL

https://app.usejump.co.uk/functions/v1/api-v1

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer pk_live_your_api_key

API keys are scoped to a single organisation. All data returned is automatically filtered to your organisation — you never need to pass an organisation ID.

Keys use the pk_live_ prefix for production and pk_test_ for test environments.

Response Format

Every response — success or error — uses the same envelope:

Success (single record)

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Sarah"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Success (list)

{
  "data": [...],
  "meta": {
    "limit": 20,
    "next_offset": 20,
    "has_more": true,
    "request_id": "req_abc123"
  }
}

Pagination

All list endpoints support limit and offset query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Records per page (1–100)
`offset`	integer	0	Records to skip

The response meta tells you if there are more records:

has_more: true means there is at least one more page
next_offset is the offset value to use for the next page (null when no more pages)

We intentionally do not return a total count — use has_more for pagination.

Filtering

List endpoints support filters via query parameters using operator suffixes:

Suffix	Meaning	Example
(none)	Exact match	`?status=open`
`_gte`	Greater than or equal	`?created_at_gte=2026-01-01`
`_lte`	Less than or equal	`?created_at_lte=2026-03-25`
`_in`	Comma-separated set	`?status_in=open,closed`

Some endpoints also support a search parameter for text search across relevant fields.

Error Handling

Errors use the same envelope with data: null and an error object:

{
  "data": null,
  "meta": {
    "request_id": "req_abc123"
  },
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "first_name": "first_name is required"
      }
    }
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORISED`	401	Missing or invalid API key
`FORBIDDEN`	403	Operation not permitted
`NOT_FOUND`	404	Resource does not exist (or belongs to a different organisation)
`VALIDATION_ERROR`	422	Request body failed validation
`INVALID_STATE_TRANSITION`	422	Action not permitted given current record state
`CONFLICT`	409	Duplicate (e.g. idempotency key reuse with different body)
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Unexpected server error

NOT_FOUND is returned for both missing records and records belonging to a different organisation. The API never confirms cross-organisation record existence.

Idempotency

For POST endpoints that create records, you can include an Idempotency-Key header to prevent duplicate creation on retries:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Same key + same body → returns the original response
Same key + different body → 409 CONFLICT
Keys expire after 24 hours

Rate Limiting

Rate limit headers are included on every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999

Interactive Explorer

Try the API directly in your browser with our API Explorer.

Rate Limits & Errors API Explorer