> For the complete documentation index, see [llms.txt](https://docs.indicio.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.indicio.tech/developer/indicio-proven-r/api-reference/invitations.md).

# Invitations

Endpoints for creating and managing invitations

## Get all invitations

> This endpoint retrieves all invitations associated with the provided API key.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations":{"get":{"summary":"Get all invitations","description":"This endpoint retrieves all invitations associated with the provided API key.","tags":["Invitations"],"parameters":[{"in":"query","name":"sort-field","schema":{"type":"string"},"description":"The field to sort by (default updated_at)."},{"in":"query","name":"sort-direction","schema":{"type":"string"},"description":"The direction to sort (ASC or DESC, default DESC)."},{"in":"query","name":"page-size","schema":{"type":"integer"},"description":"The number of invitations per page (default 20)."},{"in":"query","name":"current-page","schema":{"type":"integer"},"description":"The current page number (default 1)."},{"in":"query","name":"item-count","schema":{"type":"integer"},"description":"The total number of items."},{"in":"query","name":"state-filter","schema":{"type":"string"},"description":"If provided, returns only invitations with this state."},{"in":"query","name":"contact-id","schema":{"type":"string"},"description":"If provided, returns only invitations for this contact_id."}],"responses":{"200":{"description":"A list of invitations","content":{"application/json":{"schema":{"type":"object","properties":{"invitations":{"type":"object","properties":{"params":{"type":"object"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Unauthorized."},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Create a new invitation

> This endpoint creates a new invitation of type OOB.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations":{"post":{"summary":"Create a new invitation","description":"This endpoint creates a new invitation of type OOB.","tags":["Invitations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invitation_type"],"properties":{"invitation_type":{"type":"string","description":"The type of the invitation (OOB).","default":"OOB"},"contact_id":{"type":"string","description":"The ID of the contact.","default":"undefined"},"handshake_protocol":{"type":"string","description":"The handshake protocol for OOB invitations.","default":"undefined"},"alias":{"type":"string","description":"The alias for the invitation.","default":"undefined"},"invitation_mode":{"type":"string","description":"The mode of the invitation.","default":"undefined"},"accept":{"type":"string","description":"The accept criteria for the invitation.","default":true},"public":{"type":"boolean","description":"Whether the invitation is public.","default":false},"invitation_role":{"type":"string","description":"The role of the invitation.","default":"undefined"},"invitation_label":{"type":"string","description":"The label of the invitation.","default":"undefined"},"invitation_status":{"type":"string","description":"The status of the invitation.","default":"undefined"},"invitation_description":{"type":"string","description":"The description of the invitation.","default":"undefined"},"purpose":{"type":"string","description":"The purpose of the invitation (optional unique identifier - if provided, must be unique per wallet).","default":"undefined"},"invitation_active_starting_at":{"type":"string","format":"date-time","description":"The start time of the invitation's active period.","default":"undefined"},"invitation_active_ending_at":{"type":"string","format":"date-time","description":"The end time of the invitation's active period.","default":"undefined"},"uses_allowed":{"type":"number","description":"The number of uses allowed for the invitation.","default":"undefined"}}}}}},"responses":{"200":{"description":"Invitation created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"invitation_url":{"type":"string"},"invitation_id":{"type":"integer"},"contact_id":{"type":"string"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Unauthorized."},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Accept an invitation

> This endpoint accepts an invitation of type OOB.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations/accept":{"post":{"summary":"Accept an invitation","description":"This endpoint accepts an invitation of type OOB.","tags":["Invitations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invitation_url":{"type":"string","description":"The URL of the invitation to be accepted.","default":"undefined"}}}}}},"responses":{"200":{"description":"Invitation accepted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invitation_record":{"type":"object"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Unauthorized."},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Get invitation by ID

> This endpoint retrieves a specific invitation by its ID.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations/{invitation_id}":{"get":{"summary":"Get invitation by ID","description":"This endpoint retrieves a specific invitation by its ID.","tags":["Invitations"],"parameters":[{"in":"path","name":"invitation_id","required":true,"schema":{"type":"string"},"description":"The ID of the invitation."}],"responses":{"200":{"description":"Invitation retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"invitation":{"type":"object","description":"The retrieved invitation credential record."}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Invitation not found","content":{"application/json":{"schema":{"type":"object","properties":{"warning":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Update an invitation

> This endpoint updates an existing invitation.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations/{invitation_id}":{"put":{"summary":"Update an invitation","description":"This endpoint updates an existing invitation.","tags":["Invitations"],"parameters":[{"in":"path","name":"invitation_id","required":true,"schema":{"type":"string"},"description":"The ID of the invitation to update."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workflow_status":{"type":"string","description":"The workflow status of the invitation."},"description":{"type":"string","description":"The description of the invitation."},"purpose":{"type":"string","description":"The purpose of the invitation (unique identifier)."},"active_starting_at":{"type":"string","format":"date-time","description":"The start time of the invitation."},"active_ending_at":{"type":"string","format":"date-time","description":"The end time of the invitation."},"uses_allowed":{"type":"integer","description":"The number of uses allowed for the invitation."}}}}}},"responses":{"200":{"description":"Invitation updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"updatedInvitation":{"type":"object","description":"The updated invitation record."}}}}}},"400":{"description":"Bad request. Invalid parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Invitation record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Delete an invitation

> This endpoint deletes an existing invitation.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations/{invitation_id}":{"delete":{"summary":"Delete an invitation","description":"This endpoint deletes an existing invitation.","tags":["Invitations"],"parameters":[{"in":"path","name":"invitation_id","required":true,"schema":{"type":"string"},"description":"The ID of the invitation to delete."}],"responses":{"200":{"description":"Invitation deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"string"}}}}}},"400":{"description":"Bad request. Invalid parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Invitation record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Get invitation by purpose

> Retrieves a specific invitation by its purpose identifier.

```json
{"openapi":"3.0.0","info":{"title":"Proven API","version":"1.0.0"},"tags":[{"name":"Invitations","description":"Endpoints for creating and managing invitations"}],"servers":[{"url":"https://proven-4-2-test.proven.indicio.tech"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}}},"paths":{"/api/v1/invitations/purpose/{purpose}":{"get":{"summary":"Get invitation by purpose","description":"Retrieves a specific invitation by its purpose identifier.","tags":["Invitations"],"parameters":[{"in":"path","name":"purpose","required":true,"schema":{"type":"string"},"description":"The purpose identifier of the invitation."}],"responses":{"200":{"description":"Invitation retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"invitation":{"type":"object","description":"The retrieved invitation credential record."}}}}}},"400":{"description":"Bad request. Invalid parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Invitation not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```