Remote Travel Letters API
The Travel Letters API from Remote — 2 operation(s) for travel letters.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Travel Letters API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Travel Letters
paths:
/v1/travel-letter-requests/{id}:
get:
callbacks: {}
deprecated: false
description: 'Show a single travel letter request.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View travel letters (`travel_letter:read`) | Manage travel letters (`travel_letter:write`) |
'
operationId: get_v1_travel-letter-requests_id
parameters:
- description: travel letter request ID
example: 93t3j-travel_letter_id-9suej43
in: path
name: id
required: true
schema:
$ref: '#/components/schemas/UuidSlug'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TravelLetterResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- travel_letter:read
- travel_letter:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- travel_letter:read
- travel_letter:write
- employment_documents
- all:write
- all:read
summary: Show travel letter request
tags:
- Travel Letters
patch:
callbacks: {}
deprecated: false
description: 'Updates a travel letter request
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage travel letters (`travel_letter:write`) |
'
operationId: patch_v1_travel-letter-requests_id (2)
parameters:
- description: Travel letter Request ID
example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTravelLetterRequestParams'
description: Travel letter Request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TravelLetterResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- travel_letter:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- travel_letter:write
- employment_documents
- all:write
summary: Updates a travel letter request
tags:
- Travel Letters
put:
callbacks: {}
deprecated: false
description: 'Updates a travel letter request
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage travel letters (`travel_letter:write`) |
'
operationId: patch_v1_travel-letter-requests_id
parameters:
- description: Travel letter Request ID
example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTravelLetterRequestParams'
description: Travel letter Request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TravelLetterResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- travel_letter:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- travel_letter:write
- employment_documents
- all:write
summary: Updates a travel letter request
tags:
- Travel Letters
/v1/travel-letter-requests:
get:
callbacks: {}
deprecated: false
description: 'List travel letter requests.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View travel letters (`travel_letter:read`) | Manage travel letters (`travel_letter:write`) |
'
operationId: get_v1_travel-letter-requests
parameters:
- description: Filter results on the given status
in: query
name: status
required: false
schema:
enum:
- pending
- cancelled
- declined_by_manager
- declined_by_remote
- approved_by_manager
- approved_by_remote
type: string
- description: Filter results on the given employment slug
in: query
name: employment_id
required: false
schema:
type: string
- description: Filter results on the given employee name
in: query
name: employee_name
required: false
schema:
type: string
- description: Sort order
example: asc
in: query
name: order
required: false
schema:
enum:
- asc
- desc
type: string
- description: Field to sort by
example: submitted_at
in: query
name: sort_by
required: false
schema:
enum:
- submitted_at
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListTravelLettersResponse'
description: Success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- travel_letter:read
- travel_letter:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- travel_letter:read
- travel_letter:write
- employment_documents
- all:write
- all:read
summary: List travel letter requests
tags:
- Travel Letters
components:
schemas:
DateTimeIso8601:
description: 'UTC date time in [ISO 8601][] format.
[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
'
example: '2021-07-15T18:18:17Z'
format: date-time
title: DateTimeIso8601
type: string
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
required:
- code
- message
- action
title: ActionError
type: object
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
UuidSlug:
description: Identifier of the employment being terminated.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
UpdateTravelLetterRequestParams:
additionalProperties: false
description: Schema for updating travel letter request parameters
example:
employer_special_instructions: some special instruction
responsible_for_accommodation_cost: employee
responsible_for_meal_cost: employee
responsible_for_travel_cost: employee
status: approved_by_manager
oneOf:
- $ref: '#/components/schemas/ApprovedTravelLetter'
- $ref: '#/components/schemas/DeclinedTravelLetter'
title: UpdateTravelLetterRequestParams
DeclinedTravelLetter:
additionalProperties: false
description: Schema for declined travel letter
example:
employer_special_instructions: Some special instruction
reason: some reason
status: declined_by_manager
properties:
employer_special_instructions:
nullable: true
type: string
reason:
type: string
status:
enum:
- declined_by_manager
type: string
required:
- status
- reason
title: DeclinedTravelLetter
type: object
ListTravelLettersResponse:
description: Response schema listing many travel_letter_requests
example:
current_page: 1
total_count: 1
total_pages: 1
travel_letter_requests:
- additional_information: Some additional information
destination_country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
embassy_address: some embassy address
employer_approver:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
employer_special_instructions: Some special instruction
id: f4b4369e-cb29-47f0-a608-afd5e19a2102
reason: Some reason
requires_travel_address: false
responsible_for_accommodation_cost: employee
responsible_for_meal_cost: employee
responsible_for_travel_cost: employee
status: pending
submitted_at: '2021-07-15T18:18:17Z'
travel_address: Some travel address
travel_date_end: '2021-07-01'
travel_date_start: '2021-07-01'
travel_document_number: FC123456
travel_reason: Some travel reason
travel_reason_details: Some details
user:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
travel_letter_requests:
items:
$ref: '#/components/schemas/TravelLetterRequest'
type: array
type: object
title: ListTravelLettersResponse
type: object
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
Country:
description: A supported country on Remote
example:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
properties:
alpha_2_code:
description: The ISO 3166-1 alpha-2 country code (e.g., "PT").
type: string
code:
description: The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
type: string
contractor_products_available:
description: Contractor product names available for this country
items:
enum:
- standard
- plus
- cor
type: string
type: array
country_subdivisions:
description: Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
items:
$ref: '#/components/schemas/CountrySubdivision'
nullable: true
type: array
employment_agreement_preview_available:
description: Whether an Employment Agreement preview is available for this country.
type: boolean
eor_onboarding:
description: Whether EOR (Employer of Record) onboarding is available in this country.
type: boolean
locked_benefits:
description: When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
type: string
name:
description: The country's full English name.
type: string
region:
description: The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
type: string
subregion:
description: The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
nullable: true
type: string
supported_json_schemas:
description: The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
items:
type: string
type: array
required:
- alpha_2_code
- code
- name
title: Country
type: object
ApprovedTravelLetter:
additionalProperties: false
description: Schema for approved travel letter
example:
employer_special_instructions: some special instruction
responsible_for_accommodation_cost: employee
responsible_for_meal_cost: employee
responsible_for_travel_cost: employee
status: approved_by_manager
properties:
employer_special_instructions:
nullable: true
type: string
responsible_for_accommodation_cost:
enum:
- employee
- employer
type: string
responsible_for_meal_cost:
enum:
- employee
- employer
type: string
responsible_for_travel_cost:
enum:
- employee
- employer
type: string
status:
enum:
- approved_by_manager
type: string
required:
- status
- responsible_for_accommodation_cost
- responsible_for_travel_cost
- responsible_for_meal_cost
title: ApprovedTravelLetter
type: object
Date:
description: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
example: '2021-07-01'
format: date
title: Date
type: string
TravelLetterRequest:
additionalProperties: false
description: 'A travel letter request submitted by an employee who needs a formal letter from their employer to support a visa or travel application. The request goes through a two-stage approval: first by the employer manager, then by Remote.'
example:
additional_information: Some additional information
destination_country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
embassy_address: some embassy address
employer_approver:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
employer_special_instructions: Some special instruction
id: f4b4369e-cb29-47f0-a608-afd5e19a2102
reason: Some reason
requires_travel_address: false
responsible_for_accommodation_cost: employee
responsible_for_meal_cost: employee
responsible_for_travel_cost: employee
status: pending
submitted_at: '2021-07-15T18:18:17Z'
travel_address: Some travel address
travel_date_end: '2021-07-01'
travel_date_start: '2021-07-01'
travel_document_number: FC123456
travel_reason: Some travel reason
travel_reason_details: Some details
user:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
properties:
additional_information:
description: Additional information provided by the employee about their travel plans.
type: string
destination_country:
$ref: '#/components/schemas/Country'
embassy_address:
description: The address of the embassy or consulate where the travel letter will be submitted.
type: string
employer_approver:
$ref: '#/components/schemas/TravelLetterUser'
employer_special_instructions:
description: Special instructions from the employer to include in the travel letter. Null if none provided.
nullable: true
type: string
id:
description: The unique identifier (UUID) of the travel letter request.
format: uuid
type: string
reason:
description: The purpose of the travel (e.g., business meeting, conference, client visit).
type: string
requires_travel_address:
description: Whether the employee needs to provide a specific travel address (accommodation address at the destination).
type: boolean
responsible_for_accommodation_cost:
description: Who is responsible for accommodation costs during the trip. Set by the employer during approval. Null if not yet approved.
enum:
- employee
- employer
nullable: true
type: string
responsible_for_meal_cost:
description: Who is responsible for meal costs during the trip. Set by the employer during approval. Null if not yet approved.
enum:
- employee
- employer
nullable: true
type: string
responsible_for_travel_cost:
description: Who is responsible for transportation costs. Set by the employer during approval. Null if not yet approved.
enum:
- employee
- employer
nullable: true
type: string
status:
description: 'The current status of the travel letter request.
- `pending`: Submitted by the employee and awaiting manager review.
- `cancelled`: Cancelled by the employee before approval.
- `declined_by_manager`: The employer manager declined the request.
- `declined_by_remote`: Remote declined the request after manager approval (e.g., compliance reasons).
- `approved_by_manager`: Approved by the employer manager, awaiting Remote''s review.
- `approved_by_remote`: Fully approved by both the manager and Remote. The travel letter will be generated.
'
enum:
- pending
- cancelled
- declined_by_manager
- declined_by_remote
- approved_by_manager
- approved_by_remote
type: string
submitted_at:
$ref: '#/components/schemas/DateTimeIso8601'
travel_address:
description: The employee's accommodation address at the destination. Null if `requires_travel_address` is false or not yet provided.
nullable: true
type: string
travel_date_end:
$ref: '#/components/schemas/Date'
travel_date_start:
$ref: '#/components/schemas/Date'
travel_document_number:
description: The employee's travel document (passport) number.
type: string
travel_reason:
description: The category of travel reason selected by the employee.
type: string
travel_reason_details:
description: Detailed explanation of the travel reason provided by the employee.
type: string
user:
$ref: '#/components/schemas/TravelLetterUser'
required:
- additional_information
- destination_country
- embassy_address
- employer_approver
- employer_special_instructions
- id
- reason
- requires_travel_address
- responsible_for_accommodation_cost
- responsible_for_meal_cost
- responsible_for_travel_cost
- status
- submitted_at
- travel_address
- travel_date_end
- travel_date_start
- travel_document_number
- travel_reason
- travel_reason_details
- user
title: TravelLetterRequest
type: object
TravelLetterResponse:
additionalProperties: false
description: Schema for travel letter request
example:
data:
travel_letter_request:
additional_information: Some additional information
destination_country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
embassy_address: some embassy address
employer_approver:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
employer_special_instructions: Some special instruction
id: f4b4369e-cb29-47f0-a608-afd5e19a2102
reason: Some reason
requires_travel_address: false
responsible_for_accommodation_cost: employee
responsible_for_meal_cost: employee
responsible_for_travel_cost: employee
status: pending
submitted_at: '2021-07-15T18:18:17Z'
travel_address: Some travel address
travel_date_end: '2021-07-01'
travel_date_start: '2021-07-01'
travel_document_number: FC123456
travel_reason: Some travel reason
travel_reason_details: Some details
user:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
properties:
data:
additionalProperties: false
properties:
travel_letter_request:
$ref: '#/components/schemas/TravelLetterRequest'
required:
- travel_letter_request
type: object
required:
- data
title: TravelLetterResponse
type: object
TravelLetterUser:
additionalProperties: false
description: A user associated with a travel letter request (either the employee or the employer approver).
example:
email: user0@company.com
id: 93aaf0b3-1d79-4d2c-8d47-3d5406727d70
name: User Name
nullable: true
properties:
email:
description: The user's email address.
type: string
id:
description: The unique identifier (UUID) of the user.
format: uuid
type: string
name:
description: The user's full name.
type: string
required:
- email
- name
- id
title: TravelLetterUser
type: object
CountrySubdivision:
description: A subdivision of a supported country on Remote
example:
code: PT-11
name: Lisboa
subdivision_type: District
properties:
code:
description: The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
type: string
name:
description: The subdivision's name (e.g., "Lisboa", "California").
type: string
subdivision_type:
description: The type of subdivision (e.g., "District", "State", "Province").
type: string
required:
- name
title: CountrySubdivision
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_departm
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-travel-letters-api-openapi.yml