Clients API

Clients in Runnit are organisations linked to yours through a client relationship. The clients endpoints manage those relationships, the team of staff allowed to work on each client, and client data deletion.

All endpoints on this page live under /api/v1/organizations/:orgId/clients..., where orgId is your organisation’s id.

Authentication: every request needs a per-user API key bound to the organisation in the path. See API Keys & Authentication.

Reading client information needs any active membership in your organisation. Creating, updating, or removing clients and editing team assignments needs client-management access, which managers, admins, and owners have by default. Organisations that use custom roles may grant this differently.

Two different ids appear in these paths, so watch which one an endpoint wants:

• clientId is the id of the client relationship record.
• clientOrgId is the id of the client organisation itself. Each relationship record carries it as clientOrganizationId.

GET /api/v1/organizations/:orgId/clients

Lists all of the organisation’s clients with the client organisation’s details, sorted alphabetically by client organisation name. Any active member can call it. By default your own organisation is not in the list, because an organisation cannot be its own client.

Add ?includeInternal=1 to prepend one synthetic entry for internal work: the virtual internal client. It has id: "internal" (not a relationship id), isInternal: true, isEditable: false, createdById: null, and clientOrganizationId set to your own organisation’s id. Use that id where a client organisation id is accepted for internal work, for example a brief session’s clientOrganizationId. It is not a relationship record: the relationship endpoints below answer 404 for internal, and projects created for internal work store no client.

Example request

curl https://api.runnit.io/api/v1/organizations/<org-id>/clients \
  -H 'Authorization: Bearer rnk_your_key'

Response

{
  "success": true,
  "clients": [
    {
      "id": "<client-relationship-uuid>",
      "organizationId": "<org-uuid>",
      "clientOrganizationId": "<client-org-uuid>",
      "relationshipStatus": "active",
      "settings": {},
      "createdById": "<user-uuid>",
      "createdAt": "2026-01-05T00:00:00.000Z",
      "updatedAt": "2026-01-05T00:00:00.000Z",
      "organization": {
        "id": "<client-org-uuid>",
        "name": "Harbour Retail Group",
        "slug": "harbour-retail",
        "email": "contact@harbour.example.com"
      },
      "isEditable": true,
      "userCount": 0
    }
  ]
}

isEditable is true when you can edit the client organisation’s details through this API: the client organisation has no registered users and was not created by one of its own members. userCount is the number of active users in the client organisation.

POST /api/v1/organizations/:orgId/clients/link

Links an existing Runnit organisation as a client, using its organisation code. Requires client-management access (managers, admins, and owners by default). Linking also ensures the client has a set of default asset collections.

Request body

Name	Type	Required	Description
clientOrgCode	string	Yes	The client organisation’s code (its slug): lowercase letters, numbers, and dashes only.
settings	object	No	Relationship settings. Defaults to {}.

Example request

curl -X POST https://api.runnit.io/api/v1/organizations/<org-id>/clients/link \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "clientOrgCode": "harbour-retail" }'

Response is 201 with the new relationship, the client organisation, and its default collections:

{
  "success": true,
  "client": {
    "id": "<client-relationship-uuid>",
    "organizationId": "<org-uuid>",
    "clientOrganizationId": "<client-org-uuid>",
    "relationshipStatus": "active",
    "organization": { "id": "<client-org-uuid>", "name": "Harbour Retail Group", "slug": "harbour-retail" },
    "defaultCollections": [{ "id": "<collection-uuid>", "name": "Brand", "...": "..." }]
  }
}

Errors

Status	When
400	The code contains invalid characters, or the relationship already exists.
404	No organisation exists with that code.

POST /api/v1/organizations/:orgId/clients/create

Creates a brand-new organisation for the client and links it in one step. Requires client-management access. Default asset collections are created for the new client automatically.

Request body

Name	Type	Required	Description
name	string	Yes	The client organisation’s name.
orgCode	string	Yes	Organisation code for the new client: lowercase letters, numbers, and dashes only. Must not be taken.
addressLine1	string	No	Street address.
city	string	No	City.
country	string	No	Country.
email	string	No	Contact email; must be a valid address when supplied.
phone	string	No	Contact phone number.
url	string	No	Website address.
settings	object	No	Relationship settings. Defaults to {}.

Example request

curl -X POST https://api.runnit.io/api/v1/organizations/<org-id>/clients/create \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Harbour Retail Group",
    "orgCode": "harbour-retail",
    "city": "Sydney",
    "country": "Australia",
    "email": "contact@harbour.example.com"
  }'

Response is 201, in the same shape as the link endpoint.

Errors

Status	When
400	A required field is missing, orgCode has invalid characters or is already taken, or email is invalid.

GET /api/v1/organizations/:orgId/clients/:clientId

Returns one client relationship with the client organisation’s details. Any active member can call it. clientId is the relationship id.

curl https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-id> \
  -H 'Authorization: Bearer rnk_your_key'

Response is { "success": true, "client": { ... } } with the same client shape as the list endpoint (without isEditable and userCount). Returns 404 when the relationship does not exist or belongs to another organisation.

PUT /api/v1/organizations/:orgId/clients/:clientId

Updates the client relationship. Requires client-management access.

Request body

Name	Type	Required	Description
relationshipStatus	string	No	One of active, inactive, or pending.
settings	object	No	Replacement relationship settings.

Example request

curl -X PUT https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-id> \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "relationshipStatus": "inactive" }'

Response is { "success": true, "client": { ... } } with the updated relationship and the client organisation.

Errors

Status	When
400	relationshipStatus is not active, inactive, or pending.
404	The relationship does not exist in the organisation.

PATCH /api/v1/organizations/:orgId/clients/:clientId/organization

Updates the client organisation’s own details (name, contact, and address). Requires client-management access. This only works while the client organisation is still a shell you manage: it must have no registered users, and it must not have been created by one of its own members.

Request body (all optional)

Name	Type	Required	Description
name	string	No	Organisation name; cannot be empty when supplied.
email	string	No	Contact email; must be valid when supplied.
phone	string	No	Contact phone number.
url	string	No	Website address.
addressLine1	string	No	Street address.
city	string	No	City.
country	string	No	Country.

Example request

curl -X PATCH https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-id>/organization \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "phone": "+61 2 8000 0000" }'

Response is { "success": true, "organization": { ... } } with the updated client organisation.

Errors

Status	When
400	A supplied field fails validation.
403	The client organisation has registered users, or it belongs to its own members.
404	The relationship does not exist in the organisation.

DELETE /api/v1/organizations/:orgId/clients/:clientId

Removes the client relationship. Requires client-management access. This unlinks the client; it does not delete the client organisation or any project data. Use the data-deletion endpoint below for that.

curl -X DELETE https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-id> \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "success": true, "message": "Client relationship removed" }

Returns 404 when the relationship does not exist in the organisation.

DELETE /api/v1/organizations/:orgId/clients/:clientId/data

Deletes the data associated with a client relationship. Requires client-management access.

Caution

This endpoint is destructive and cannot be undone. scope=engagement deletes the client’s delivery data (projects, tasks, and related records) but keeps the relationship and the client organisation. scope=full also deletes the relationship, the client organisation’s assets, and the client organisation itself. Take a backup or export anything you need before calling it.

Query parameters

Name	Type	Required	Description
scope	string	No	engagement (default) or full. Any other value is treated as engagement.

Example request

curl -X DELETE 'https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-id>/data?scope=full' \
  -H 'Authorization: Bearer rnk_your_key'

Response

{
  "success": true,
  "message": "Client data deleted successfully",
  "scope": "full",
  "summary": { "...": "counts of the records that were removed" }
}

Errors

Status	When
404	The relationship does not exist in the organisation.

GET /api/v1/organizations/:orgId/clients/:clientOrgId/team

Returns the team that can work on a client. Any active member can call it. Note this endpoint takes the client organisation id, not the relationship id.

If the client has no assignment restrictions, the team is every active member of your organisation. If anyone has been explicitly assigned, the team is only those assigned people.

curl https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-org-id>/team \
  -H 'Authorization: Bearer rnk_your_key'

Response

{
  "success": true,
  "hasRestrictions": true,
  "team": [
    {
      "id": "<user-uuid>",
      "email": "priya@example.com",
      "firstName": "Priya",
      "lastName": "Shah",
      "displayName": "Priya Shah",
      "avatarUrl": null,
      "currentTitle": "Senior Producer",
      "role": "manager",
      "isFreelancer": false
    }
  ]
}

Errors

Status	When
404	There is no client relationship with that client organisation.

GET /api/v1/organizations/:orgId/clients/:clientOrgId/assignments

Returns the explicit client staffing list, excluding staff who are available because the client uses the all-staff default. Project-only members aren’t included. Any active member can call it.

curl https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-org-id>/assignments \
  -H 'Authorization: Bearer rnk_your_key'

Response

{
  "success": true,
  "assignments": [
    {
      "id": "<assignment-uuid>",
      "userId": "<user-uuid>",
      "organizationId": "<org-uuid>",
      "clientOrganizationId": "<client-org-uuid>",
      "user": {
        "id": "<user-uuid>",
        "email": "priya@example.com",
        "firstName": "Priya",
        "lastName": "Shah",
        "displayName": "Priya Shah",
        "currentTitle": "Senior Producer"
      }
    }
  ]
}

Returns 404 when there is no client relationship with that client organisation.

PUT /api/v1/organizations/:orgId/clients/:clientOrgId/assignments

Replaces the client’s default staffing list. Requires client-management access.

Passing specific user ids sets the people AI and planners should consider first. These people also see all projects for the client by default. A project owner can still add another active staff member to one project without changing this list. Passing an empty array restores the all-staff default.

Request body

Name	Type	Required	Description
userIds	array of UUIDs	Yes	The complete default staffing list for this client. An empty array restores the all-staff default.

Example request

curl -X PUT https://api.runnit.io/api/v1/organizations/<org-id>/clients/<client-org-id>/assignments \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "userIds": ["<user-id-1>", "<user-id-2>"] }'

Response

{
  "success": true,
  "message": "Client team updated",
  "hasRestrictions": true,
  "team": [{ "...": "same member shape as the team endpoint" }]
}

Errors

Status	When
400	userIds is missing, not an array, or contains a value that is not a UUID.
404	There is no client relationship with that client organisation.

Client portal endpoints

The API also mounts the client portal’s job endpoints under /api/v1/client/jobs. They serve the client side of a relationship: they only return data when the key belongs to a user in the client organisation itself, with visibility filtering applied. Keys created in the delivering organisation cannot use them, so they are not documented further here.

Next step

Set client-specific billing with the Rate Cards API, or manage per-person client access from the other direction with the Staff Profiles & Work History API.