> ## Documentation Index > Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Invitation > Create an invitation with a magic link to onboard a fleet. Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the fleet to begin the onboarding process. Once accepted, a share agreement is automatically created to enable data sharing. **Note:** If an active, accepted, or declined invitation already exists for the same `fleet_ref`, the invitation is refreshed (expiration extended, tokens regenerated if accepted, reactivated if declined) and returned with status code 200 instead of 201. ## OpenAPI ````yaml https://api.catenatelematics.com/v2/orgs/openapi.json post /v2/orgs/invitations openapi: 3.1.0 info: title: Telematics Organizations Service - REST API description: Organizations Service REST API version: 0.1.0 servers: - url: https://api.catenatelematics.com description: Catena Telematics API security: [] tags: - name: Invitations description: >- Send invitations to onboard fleets. Create magic links, track invitation status, and manage the fleet onboarding workflow. - name: Share Agreements description: >- Manage data sharing agreements with fleets. Monitor agreement status, update terms, and control access to fleet telematics data. - name: Fleets description: >- View and manage fleet profiles. Access fleet information for fleets you've successfully onboarded through invitations. - name: Partners description: >- Manage your partner organization profile. Update company information, websites, and service categories visible to fleets. - name: TSPs description: >- Browse available Telematics Service Providers (TSPs). View supported integrations that fleets can connect to share their telematics data. paths: /v2/orgs/invitations: post: tags: - Invitations summary: Create Invitation description: >- Create an invitation with a magic link to onboard a fleet. Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the fleet to begin the onboarding process. Once accepted, a share agreement is automatically created to enable data sharing. **Note:** If an active, accepted, or declined invitation already exists for the same `fleet_ref`, the invitation is refreshed (expiration extended, tokens regenerated if accepted, reactivated if declined) and returned with status code 200 instead of 201. operationId: create_invitation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvitationCreate' responses: '200': description: Existing invitation refreshed (already exists for this fleet_ref) content: application/json: schema: $ref: '#/components/schemas/InvitationRead' '201': description: New invitation created content: application/json: schema: $ref: '#/components/schemas/InvitationRead' '400': content: application/json: schema: $ref: '#/components/schemas/BadRequest' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/Unauthorized' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' description: Not Found '405': content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' description: Method Not Allowed '409': content: application/json: schema: $ref: '#/components/schemas/Conflict' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' description: Unprocessable Entity '429': content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: Internal Server Error security: - Bearer: - invitation:create components: schemas: InvitationCreate: properties: fleet_ref: type: string title: Fleet Reference description: >- Your internal fleet identifier. Use this to map Catena fleets back to your system. This value will be returned in webhooks and redirect URLs. fleet_name: anyOf: - type: string - type: 'null' title: Fleet Name description: >- Pre-populate the fleet name during onboarding. The fleet can modify this during acceptance. Only letters, numbers, and spaces are allowed. fleet_email: anyOf: - type: string format: email - type: 'null' title: Fleet Email description: >- Pre-populate the fleet contact email. Optional but recommended for faster onboarding. fleet_regulatory_id: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID description: >- Pre-populate the fleet's regulatory identifier (e.g., DOT number, EASA ID). Helps with fleet verification. fleet_regulatory_id_type: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID Type description: >- Pre-populate the type of regulatory ID provided (e.g., DOT, EASA, MC). Required if regulatory_id is set. fleet_phone: anyOf: - type: string format: phone - type: 'null' title: Fleet Phone description: Pre-populate the phone number of the fleet fleet_website: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Fleet website description: Pre-populate the website of the fleet fleet_country_code: anyOf: - type: string pattern: ^\w{3}$ - type: 'null' title: Fleet Country Code description: Pre-populate the country code of the fleet success_redirect_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Success Redirect URL description: >- The URL to redirect the user to after onboarding successfully on Catena Connect. **Available query parameters:** `invitation_id`, `fleet_ref`. failure_redirect_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Failure Redirect URL description: >- The URL to redirect the user to after failing to onboard on Catena Connect (i.e. declining an invitation, opening an expired invitation, etc). **Available query parameters:** `invitation_id`, `fleet_ref`. callback_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Callback URL description: >- Your webhook endpoint to receive real-time notifications for invitation acceptance, share agreement creation, and connection status updates. Must be HTTPS. limit_tsps: anyOf: - items: type: string type: array - type: 'null' title: Limit TSPs description: >- Restrict which telematics providers the fleet can connect to. Useful if you only need data from specific TSPs. If omitted, all available TSPs are shown. permissions: anyOf: - additionalProperties: $ref: '#/components/schemas/ShareLevelEnum' propertyNames: $ref: '#/components/schemas/ResourceEnum' type: object - type: 'null' title: Required Permissions description: >- Defines which resources (vehicle, locations, users, etc.) the fleet must grant access to and the permission level (read, write) for each. If omitted, we will require READ permissions for all resources. expires_in_hours: type: integer maximum: 672 minimum: 1 title: Expires In Hours description: >- How long the invitation link remains valid (1-672 hours). Default is 24 hours. *Consider longer durations for email campaigns.* default: 24 partner_provided_fleet_name: anyOf: - type: string - type: 'null' title: Fleet Name (Deprecated) description: >- **Deprecated: Use `fleet_name` instead.** Pre-populate the fleet name during onboarding. deprecated: true partner_provided_fleet_email: anyOf: - type: string format: email - type: 'null' title: Fleet Email (Deprecated) description: >- **Deprecated: Use `fleet_email` instead.** Pre-populate the fleet contact email. deprecated: true partner_provided_fleet_regulatory_id: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID (Deprecated) description: >- **Deprecated: Use `fleet_regulatory_id` instead.** Pre-populate the fleet's regulatory identifier. deprecated: true partner_provided_fleet_regulatory_id_type: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID Type (Deprecated) description: >- **Deprecated: Use `fleet_regulatory_id_type` instead.** Pre-populate the type of regulatory ID. deprecated: true partner_provided_fleet_phone: anyOf: - type: string format: phone - type: 'null' title: Fleet Phone (Deprecated) description: >- **Deprecated: Use `fleet_phone` instead.** Pre-populate the phone number of the fleet. deprecated: true partner_provided_fleet_website: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Fleet Website (Deprecated) description: >- **Deprecated: Use `fleet_website` instead.** Pre-populate the website of the fleet. deprecated: true partner_provided_fleet_country_code: anyOf: - type: string pattern: ^\w{3}$ - type: 'null' title: Fleet Country Code (Deprecated) description: >- **Deprecated: Use `fleet_country_code` instead.** Pre-populate the country code of the fleet. deprecated: true type: object required: - fleet_ref title: InvitationCreate description: API model for creating a fleet invitation example: {} InvitationRead: properties: id: type: string format: uuid title: Id description: Unique invitation identifier created_at: type: string format: date-time title: Created At description: When the invitation was created magic_link: type: string title: Magic Link description: >- The magic link that is used to open Catena Connect and accept the invitation. Share this URL with the fleet to begin onboarding. expires_at: type: string format: date-time title: Invitation Expiration description: The expiration date and time of the invitation expires_in_hours: type: integer title: Expires In Hours description: The number of hours the invitation is valid for. status: $ref: '#/components/schemas/InvitationStatusEnum' title: Status description: >- The current status of the invitation (active, accepted, declined, or expired) fleet_name: anyOf: - type: string - type: 'null' title: Fleet Name description: >- Pre-populate the fleet name during onboarding. The fleet can modify this during acceptance. accepted_at: anyOf: - type: string format: date-time - type: 'null' title: Accepted At description: The date and time the invitation was accepted. Null if not accepted. pre_registration_access_token: anyOf: - type: string - type: 'null' title: Pre-Registration JWT Token description: >- The JWT token used to pre-register the fleet. It allows the fleet to create connections after accepting the invitation even without registering a user. Value is set after the invitation is accepted. pre_registration_refresh_token: anyOf: - type: string - type: 'null' title: Pre-Registration Refresh Token description: >- The refresh token used to pre-register the fleet. It allows the fleet to create connections after accepting the invitation even without registering a user. Value is set after the invitation is accepted. callback_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Callback URL description: >- Your webhook endpoint to receive real-time notifications for invitation acceptance, share agreement creation, and connection status updates. Must be HTTPS. success_redirect_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Success Redirect URL description: >- The URL to redirect the user to after onboarding successfully on Catena Connect. **Available query parameters:** `invitation_id`, `fleet_ref`. failure_redirect_url: anyOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' title: Failure Redirect URL description: >- The URL to redirect the user to after failing to onboard on Catena Connect (i.e. declining an invitation, opening an expired invitation, etc). **Available query parameters:** `invitation_id`, `fleet_ref`. limit_tsps: anyOf: - items: type: string type: array - type: 'null' title: Limit TSPs description: >- Restrict which telematics providers the fleet can connect to. Useful if you only need data from specific TSPs. If omitted, all available TSPs are shown. fleet_id: anyOf: - type: string format: uuid - type: 'null' title: Fleet ID description: >- The Catena fleet ID created after accepting the invitation. Null if invitation has not been accepted. partner_slug: anyOf: - type: string - type: 'null' title: Partner Slug description: The slug of your organization partner_id: type: string format: uuid title: Partner ID description: Your organization ID requesting access to fleet data decline_reason: anyOf: - type: string - type: 'null' title: Decline Reason description: >- The reason provided by the fleet for declining the invitation. Null if invitation was not declined. declined_at: anyOf: - type: string format: date-time - type: 'null' title: Declined At description: >- The date the invitation was declined by the fleet. Null if invitation was not declined. fleet_ref: type: string title: Fleet Reference description: >- Your internal fleet identifier. Use this to map Catena fleets back to your system. This value will be returned in webhooks and redirect URLs. permissions: additionalProperties: $ref: '#/components/schemas/ShareLevelEnum' propertyNames: $ref: '#/components/schemas/ResourceEnum' type: object title: Required Permissions description: >- Defines which resources (vehicle, locations, users, etc.) the fleet must grant access to and the permission level (read, write) for each. fleet_email: anyOf: - type: string format: email - type: 'null' title: Fleet Email description: The contact email for the fleet. fleet_regulatory_id: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID description: The fleet's regulatory identifier (e.g., DOT number). fleet_regulatory_id_type: anyOf: - type: string - type: 'null' title: Fleet Regulatory ID Type description: The type of regulatory ID (e.g., 'DOT', 'MC'). fleet_phone: anyOf: - type: string - type: 'null' title: Fleet Phone description: The phone number for the fleet. fleet_website: anyOf: - type: string - type: 'null' title: Fleet Website description: The website URL for the fleet. fleet_country_code: anyOf: - type: string - type: 'null' title: Fleet Country Code description: The ISO 3166-1 alpha-3 country code for the fleet. partner_provided_fleet_name: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Name description: 'Deprecated: Use `fleet_name` instead.' deprecated: true readOnly: true partner_provided_fleet_email: anyOf: - type: string format: email - type: 'null' title: Partner Provided Fleet Email description: 'Deprecated: Use `fleet_email` instead.' deprecated: true readOnly: true partner_provided_fleet_regulatory_id: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Regulatory Id description: 'Deprecated: Use `fleet_regulatory_id` instead.' deprecated: true readOnly: true partner_provided_fleet_regulatory_id_type: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Regulatory Id Type description: 'Deprecated: Use `fleet_regulatory_id_type` instead.' deprecated: true readOnly: true partner_provided_fleet_phone: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Phone description: 'Deprecated: Use `fleet_phone` instead.' deprecated: true readOnly: true partner_provided_fleet_website: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Website description: 'Deprecated: Use `fleet_website` instead.' deprecated: true readOnly: true partner_provided_fleet_country_code: anyOf: - type: string - type: 'null' title: Partner Provided Fleet Country Code description: 'Deprecated: Use `fleet_country_code` instead.' deprecated: true readOnly: true type: object required: - id - created_at - magic_link - expires_at - expires_in_hours - status - fleet_name - accepted_at - pre_registration_access_token - pre_registration_refresh_token - callback_url - success_redirect_url - failure_redirect_url - limit_tsps - partner_slug - partner_id - decline_reason - declined_at - fleet_ref - permissions - fleet_email - fleet_regulatory_id - fleet_regulatory_id_type - fleet_phone - fleet_website - fleet_country_code - partner_provided_fleet_name - partner_provided_fleet_email - partner_provided_fleet_regulatory_id - partner_provided_fleet_regulatory_id_type - partner_provided_fleet_phone - partner_provided_fleet_website - partner_provided_fleet_country_code title: InvitationRead description: >- API model for reading a fleet invitation Contains the complete invitation state including acceptance/decline status. Use this to track invitation lifecycle and retrieve tokens for accepted invitations. example: accepted_at: '2025-12-11T14:22:00Z' callback_url: https://api.example.com/webhooks/catena created_at: '2025-12-11T10:30:00Z' expires_at: '2025-12-12T10:30:00Z' expires_in_hours: 24 failure_redirect_url: https://app.example.com/onboarding/failure fleet_id: 98765432-10fe-dcba-9876-543210fedcba fleet_name: Swift Transport LLC fleet_ref: FLEET-12345 id: 01234567-89ab-cdef-0123-456789abcdef limit_tsps: - samsara - geotab magic_link: >- https://connect.catenatelematics.com/?invite=01234567-89ab-cdef-0123-456789abcdef partner_id: 11223344-5566-7788-99aa-bbccddeeff00 partner_slug: acme-logistics permissions: hos_events: read user: read_write vehicle: read_write vehicle_location: read pre_registration_access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... pre_registration_refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... status: accepted success_redirect_url: https://app.example.com/onboarding/success BadRequest: properties: code: type: integer title: Code default: 400 message: type: string title: Message default: Bad Request detail: anyOf: - type: string - type: 'null' title: Detail type: object title: BadRequest Unauthorized: properties: code: type: integer title: Code default: 401 message: type: string title: Message default: Unauthorized detail: anyOf: - type: string - type: 'null' title: Detail type: object title: Unauthorized Forbidden: properties: code: type: integer title: Code default: 403 message: type: string title: Message default: Forbidden detail: anyOf: - type: string - type: 'null' title: Detail type: object title: Forbidden NotFound: properties: code: type: integer title: Code default: 404 message: type: string title: Message default: Not Found detail: anyOf: - type: string - type: 'null' title: Detail type: object title: NotFound MethodNotAllowed: properties: code: type: integer title: Code default: 405 message: type: string title: Message default: Method Not Allowed detail: anyOf: - type: string - type: 'null' title: Detail type: object title: MethodNotAllowed Conflict: properties: code: type: integer title: Code default: 409 message: type: string title: Message default: Conflict detail: anyOf: - type: string - type: 'null' title: Detail type: object title: Conflict UnprocessableEntity: properties: code: type: integer title: Code default: 422 message: type: string title: Message default: Invalid Request Body detail: anyOf: - items: $ref: '#/components/schemas/ValidationErrorDetail' type: array - type: 'null' title: Detail type: object title: UnprocessableEntity TooManyRequests: properties: code: type: integer title: Code default: 429 message: type: string title: Message default: Too Many Requests detail: anyOf: - $ref: '#/components/schemas/RetryAfterDetail' - type: 'null' type: object title: TooManyRequests InternalServerError: properties: message: type: string title: Message default: Internal Server Error type: object title: InternalServerError ShareLevelEnum: type: string enum: - read - read_write title: ShareLevelEnum description: Enum for the level of access granted InvitationStatusEnum: type: string enum: - active - accepted - declined - expired - deleted title: InvitationStatusEnum description: Enum for invitation status ValidationErrorDetail: properties: path: type: string title: Path input: type: string title: Input message: type: string title: Message error_type: type: string title: Error Type type: object required: - path - input - message - error_type title: ValidationErrorDetail RetryAfterDetail: properties: retry_after_seconds: type: integer title: Retry After Seconds message: type: string title: Message type: object required: - retry_after_seconds - message title: RetryAfterDetail securitySchemes: Bearer: type: oauth2 flows: clientCredentials: refreshUrl: >- https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token scopes: {} tokenUrl: >- https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token authorizationCode: refreshUrl: >- https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token scopes: {} authorizationUrl: >- https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/auth tokenUrl: >- https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token ````