# Members

Links users to organizations, with their permissions

Base URL: `https://api.cv-transformer.com/v1`. Endpoints: `GET /members`, `PATCH /members`, `POST /members`, `DELETE /members`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.cv-transformer.com/en/api-reference/authentication.md)).

## The member object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. Read-only. |
| `external_id` | `string \| number \| null` | Identifier of the member in an external system, used to match imported candidates. |
| `organization_id` | `uuid` | Identifier of the related organization. Read-only. References [`organizations.id`](https://www.cv-transformer.com/en/api-reference/organizations.md). |
| `user_id` | `uuid` | Identifier of the related user. Read-only. References [`user_profiles.user_id`](https://www.cv-transformer.com/en/api-reference/user_profiles.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. Read-only. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. |
| `permissions` | `Array<Permission>` | Permissions of the member. |
| `values` | `Record<string, MemberValue>` | Values for each of the organization's `member_variables`, usable in layouts. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "external_id": "example-id",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T12:00:00+00:00",
  "updated_at": "2026-01-01T12:00:00+00:00",
  "permissions": [
    "billing",
    "edit_candidates",
    "edit_layouts",
    "settings",
    "team",
    "view_candidates"
  ],
  "values": {
    "first_name": "John",
    "last_name": "Doe"
  }
}
```

### Types

```typescript
type MemberValue = 
  | {
      start: string;
      end: string;
    }
  | string
  | number
  | null;

type Permission = 
  | "billing"
  | "edit_candidates"
  | "edit_layouts"
  | "settings"
  | "team"
  | "view_candidates";
```

### Related resources

Embed related resources with the [`select` parameter](https://www.cv-transformer.com/en/api-reference/selecting.md), for example `select=*,organizations!organization_id(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `organizations!organization_id(*)` | `object \| null` | The [organization](https://www.cv-transformer.com/en/api-reference/organizations.md) referenced by `organization_id`. |
| `user_profiles(*)` | `object \| null` | The [user profile](https://www.cv-transformer.com/en/api-reference/user_profiles.md) referenced by `user_id`. |
| `candidates(*)` | `array` | The [candidates](https://www.cv-transformer.com/en/api-reference/candidates.md) referencing this member through `candidates.member_id`. |

## List members

`GET /v1/members` · requires the `members:read` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/en/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.cv-transformer.com/en/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.cv-transformer.com/en/api-reference/sorting-pagination.md)).

```bash
curl "https://api.cv-transformer.com/v1/members?limit=10&select=*" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of members with the selected columns. The `Content-Range` header holds the range returned and the total count, like `0-9/42`.
- `206`: Partial Content
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

## Update members

`PATCH /v1/members` · requires the `members:write` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/en/api-reference/filtering.md)). Without filters, this request updates all members the API key has access to. Always filter on at least one column, like `id=eq.{id}`. The body holds the attributes to change.

```bash
curl -X PATCH "https://api.cv-transformer.com/v1/members?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "billing",
      "edit_candidates",
      "edit_layouts",
      "settings",
      "team",
      "view_candidates"
    ]
  }'
```

Responses:

- `204`: Updated. With the header `Prefer: return=representation`, the response is a `200` whose body holds the updated members with the selected columns.
- `400`: The request is malformed, for example an unknown column, an invalid filter or an invalid body.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs, or no permission for this change, for example when writing rows of another organization.
- `409`: The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

## Invite member

`POST /v1/members` · requires the `members:write` scope

Invite a member to your organization. The member will receive an email with a link to accept the invitation. The member will have the user role. To make a member admin or superuser use the dashboard.

Body:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes | The email address of the member to invite. |
| `language` | `Language` | No | The language of the member to invite. |
| `name` | `string` | No | The name of the member to invite. |
| `permissions` | `Array<Permission>` | No | The permissions of the member. Defaults to editing candidates and layouts, and viewing candidates. |
| `silent` | `boolean` | No | Whether to skip the invitation email. |

```bash
curl "https://api.cv-transformer.com/v1/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "johndoe@example.com", "name": "John Doe" }'
```

Responses:

- `201`: The invited member
- `400`: The body is invalid: not JSON, a required field is missing or a field has the wrong type or value. The details name each invalid field and why.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

## Revoke member

`DELETE /v1/members` · requires the `members:write` scope

Revoke a member from your organization. The member will no longer have access to your organization. Only works for members with the user role. To revoke an admin or superuser members use the dashboard.

Query parameters:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `uuid` | Yes | The identifier of the member to revoke. |

```bash
curl -X DELETE "https://api.cv-transformer.com/v1/members?id=00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: The deleted member
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `404`: The member doesn't exist in the API key's organization.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

Errors have a JSON body with a `message`, `details` and `hint`, and for database errors a `code`. See the [introduction](https://www.cv-transformer.com/en/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.cv-transformer.com/v1/openapi.json.