> ## 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 Tms Invitation > Create an invitation with a magic link to onboard a TMS account. Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the TMS account to begin the onboarding process. Once accepted, a TMS share agreement is automatically created to enable data sharing. **Note:** If an active, accepted, or declined invitation already exists for the same `tms_account_ref`, the invitation is refreshed (expiration extended, 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/tms-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. - name: TMS description: >- Browse available Transportation Management Systems (TMS). View supported integrations that fleets can connect to share their transportation management data. - name: TMS Accounts description: >- Manage TMS accounts (tenants). Register and administer accounts that connect to Transportation Management Systems. - name: TMS Invitations description: >- Send invitations to onboard TMS accounts. Create magic links, track invitation status, and manage the TMS account onboarding workflow. - name: TMS Share Agreements description: >- Manage data sharing agreements with TMS accounts. Monitor agreement status and control access to TMS-sourced data. - name: Usage description: >- Review partner data consumption. Fetch monthly usage rollups and per-entity usage rows for billing and reporting. paths: /v2/orgs/tms-invitations: post: tags: - TMS Invitations summary: Create Tms Invitation description: >- Create an invitation with a magic link to onboard a TMS account. Returns an invitation object with a unique ID that serves as the magic link token. Share this link with the TMS account to begin the onboarding process. Once accepted, a TMS share agreement is automatically created to enable data sharing. **Note:** If an active, accepted, or declined invitation already exists for the same `tms_account_ref`, the invitation is refreshed (expiration extended, reactivated if declined) and returned with status code 200 instead of 201. operationId: create_tms_invitation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TmsInvitationCreate' responses: '200': description: >- Existing invitation refreshed (already exists for this tms_account_ref) content: application/json: schema: $ref: '#/components/schemas/TmsInvitationRead' '201': description: New invitation created content: application/json: schema: $ref: '#/components/schemas/TmsInvitationRead' '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: - tms_invitation:create components: schemas: TmsInvitationCreate: properties: tms_account_ref: type: string title: TMS Account Reference description: >- Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system. This value will be returned in webhooks and redirect URLs. limit_tms: anyOf: - items: type: string type: array - type: 'null' title: Limit TMS description: >- Restrict which transportation management systems the TMS account can connect to. Useful if you only need data from specific TMSs. If omitted, all available TMSs are shown. Cannot be combined with `exclude_tms`. exclude_tms: anyOf: - items: type: string type: array - type: 'null' title: Exclude TMS description: >- Exclude specific transportation management systems from the ones shown to the TMS account. Useful if you want the TMS account to have access to every TMS except a few. Cannot be combined with `limit_tms`. 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. default: 24 type: object required: - tms_account_ref title: TmsInvitationCreate description: API model for creating a TMS account invitation TmsInvitationRead: 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 used to accept the invitation. Share this URL with the TMS account 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/TmsInvitationStatusEnum' title: Status description: >- The current status of the invitation (active, accepted, declined, expired, or deleted) tms_account_ref: type: string title: TMS Account Reference description: >- Your internal identifier for the TMS account. Use this to map Catena TMS accounts back to your system. tms_account_id: anyOf: - type: string format: uuid - type: 'null' title: TMS Account ID description: >- The Catena TMS account ID created after accepting the invitation. Null if invitation has not been accepted. partner_id: type: string format: uuid title: Partner ID description: Your organization ID requesting access to TMS account data partner_slug: anyOf: - type: string - type: 'null' title: Partner Slug description: The slug of your organization 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. accepted_by: anyOf: - type: string - type: 'null' title: Accepted By description: >- Identifier of who accepted the invitation on behalf of the TMS account. Null if not accepted. decline_reason: anyOf: - type: string - type: 'null' title: Decline Reason description: >- The reason provided 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. Null if invitation was not declined. limit_tms: anyOf: - items: type: string type: array - type: 'null' title: Limit TMS description: >- Restrict which transportation management systems the TMS account can connect to. exclude_tms: anyOf: - items: type: string type: array - type: 'null' title: Exclude TMS description: >- Exclude specific transportation management systems from the ones shown to the TMS account. type: object required: - id - created_at - magic_link - expires_at - expires_in_hours - status - tms_account_ref - partner_id - partner_slug - accepted_at - accepted_by - decline_reason - declined_at - limit_tms - exclude_tms title: TmsInvitationRead description: API model for reading a TMS account invitation 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 TmsInvitationStatusEnum: type: string enum: - active - accepted - declined - expired - deleted title: TmsInvitationStatusEnum description: Enum for TMS 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 ````