Remote Subscriptions API
The Subscriptions API from Remote — 7 operation(s) for subscriptions.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Subscriptions API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Subscriptions
paths:
/v1/contractors/employments/{employment_id}/contractor-subscriptions:
get:
callbacks: {}
deprecated: false
description: 'Endpoint that can be used to list contractor subscriptions.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |
'
operationId: get_v1_contractors_employments_employment_id_contractor-subscriptions
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorSubscriptionSummariesResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
summary: List contractor subscriptions
tags:
- Subscriptions
/v1/contractors/cor-termination-requests:
get:
callbacks: {}
deprecated: false
description: 'Lists Contractor of Record termination requests for your company,
optionally filtered by employment and status.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |
'
operationId: get_v1_contractors_cor-termination-requests
parameters:
- description: Filter termination requests by employment ID.
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: query
name: employment_id
required: false
schema:
$ref: '#/components/schemas/UuidSlug'
- description: Filter termination requests by status.
example: initiated
in: query
name: status
required: false
schema:
enum:
- initiated
- executed
- cancelled
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/IndexCorTerminationRequestsResponse'
description: Success
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
summary: List contractor of record (COR) termination requests
tags:
- Subscriptions
/v1/contractors/employments/{employment_id}/cor-termination-requests:
post:
callbacks: {}
deprecated: false
description: 'Initiates a termination request for a Contractor of Record employment.
When a termination request is sent, a stop work order is issued and the contractor remains active until a final invoice is paid or waived.
Currently, only Contractor of Record employments can be terminated.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_contractors_employments_employment_id_cor-termination-requests
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CorTerminationRequestCreatedResponse'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'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
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Create a contractor of record (COR) termination request
tags:
- Subscriptions
/v1/contractors/employments/{employment_id}/cor-termination-requests/{termination_request_id}:
get:
callbacks: {}
deprecated: false
description: 'Retrieves a Contractor of Record termination request by ID.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |
'
operationId: get_v1_contractors_employments_employment_id_cor-termination-requests_termination_request_id
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
- description: Termination Request ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: termination_request_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CorTerminationRequestResponse'
description: Success
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:read
- employment:write
- employments
- all:write
- all:read
summary: Show a contractor of record (COR) termination request
tags:
- Subscriptions
/v1/contractors/employments/{employment_id}/terminate-cor-employment:
post:
callbacks: {}
deprecated: true
description: '**Deprecated.** Use `POST /contractors/employments/{employment_id}/cor-termination-requests` instead.
Initiates a termination request for a Contractor of Record employment.
When a termination request is sent, a stop work order is issued and the contractor remains active until a final invoice is paid or waived.
Currently, only Contractor of Record employments can be terminated.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_contractors_employments_employment_id_terminate-cor-employment
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'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
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Terminate contractor of record employment
tags:
- Subscriptions
/v1/contractors/employments/{employment_id}/contractor-plus-subscription:
post:
callbacks: {}
deprecated: false
description: 'Endpoint that can be used to upgrade, assign or downgrade a contractor''s subscription.
This can be used when company admins desire to assign someone to the Contractor Plus plan,
but also to change the contractor''s subscription between Plus and Standard.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_contractors_employments_employment_id_contractor-plus-subscription
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageContractorPlusSubscriptionOperationsParams'
description: Manage Contractor Plus subscription params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Manage contractor plus subscription
tags:
- Subscriptions
/v1/contractors/employments/{employment_id}/contractor-cor-subscription:
delete:
callbacks: {}
deprecated: false
description: 'Deletes Contractor of Record subscription intent.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: delete_v1_contractors_employments_employment_id_contractor-cor-subscription
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
responses:
'204':
content:
text/plain: {}
description: No Content
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'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
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Delete contractor of record subscription intent
tags:
- Subscriptions
post:
callbacks: {}
deprecated: false
description: 'Assigns Contractor of Record subscription in pending state to employment.
Once risk analysis is performed, subscription may start upon contract signing,
or might be denied.
Requires a non-blocking eligibility questionnaire to be submitted before creating the subscription intent.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employments (`employments`) | - | Manage employments (`employment:write`) |
'
operationId: post_v1_contractors_employments_employment_id_contractor-cor-subscription
parameters:
- description: Employment ID
example: c0a167b8-459d-4e96-9766-7a04c160892e
in: path
name: employment_id
required: true
schema:
type: string
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
description: Forbidden
'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
- employment:write
- employments
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- employment:write
- employments
- all:write
summary: Create contractor of record subscription intent
tags:
- Subscriptions
components:
schemas:
ContractorSubscriptions.Summary:
additionalProperties: false
example:
company_product:
slug: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
company_product_discount:
expiration_date: '2021-07-01'
percent: '-123.456'
currency:
code: EUR
name: European Euro
slug: eur-3b840951-099f-4bd5-90b9-032f7bfe51d9
symbol: €
eligibility_questionnaire:
is_blocking: true
questions:
question_key1: This is the label of the question
question_key2: This is another question label
responses:
question_key1: 'yes'
question_key2: 'no'
slug: fd32b683-a94a-4496-a0c4-726c088af483
submitted_at: '2021-07-15T18:18:17'
type: contractor_of_record
price:
amount: 2900
final_amount: 2610
product:
description: EOR Monthly
features:
- Feature 1
- Feature 2
frequency: monthly
name: EOR Monthly
short_name: EOR
tier: standard
total_amount: 5800
total_discount: 1000
total_in_advance: 2800
total_prorated: 3000
properties:
company_product:
properties:
slug:
$ref: '#/components/schemas/UuidSlug'
type: object
company_product_discount:
additionalProperties: false
properties:
expiration_date:
$ref: '#/components/schemas/Date'
percent:
$ref: '#/components/schemas/Decimal'
type: object
currency:
$ref: '#/components/schemas/Currency'
eligibility_questionnaire:
$ref: '#/components/schemas/EligibilityQuestionnaire'
is_termination_fees_enabled:
type: boolean
price:
properties:
amount:
type: integer
final_amount:
description: The price after applying the company discount, in cents
type: integer
type: object
product:
$ref: '#/components/schemas/Product'
total_amount:
format: integer
nullable: true
type: number
total_discount:
format: integer
type: number
total_in_advance:
format: integer
type: number
total_prorated:
format: integer
type: number
required:
- company_product
- company_product_discount
- currency
- price
- product
- total_amount
title: ContractorSubscriptions.Summary
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
EligibilityQuestionnaire:
additionalProperties: false
example:
is_blocking: true
questions:
question_key1: This is the label of the question
question_key2: This is another question label
responses:
question_key1: 'yes'
question_key2: 'no'
slug: fd32b683-a94a-4496-a0c4-726c088af483
submitted_at: '2021-07-15T18:18:17'
type: contractor_of_record
properties:
is_blocking:
description: Whether the questionnaire blocks further progress if failed
type: boolean
questions:
description: The questions in the questionnaire
type: object
responses:
description: The responses to the questionnaire
type: object
slug:
$ref: '#/components/schemas/UuidSlug'
submitted_at:
$ref: '#/components/schemas/DateTime'
type:
enum:
- contractor_of_record
example: contractor_of_record
nullable: false
type: string
required:
- slug
- is_blocking
- type
- submitted_at
- questions
- responses
title: EligibilityQuestionnaire
type: object
Decimal:
description: A decimal number represented as a string to preserve precision. Supports negative values and fractional digits.
example: '-123.456'
pattern: ^-?\d+(\.\d+)?$
title: Decimal
type: string
ContractorSubscriptionSummariesResponse:
description: Summaries of contractor subscriptions
example:
data:
- company_product:
slug: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
company_product_discount:
expiration_date: '2021-07-01'
percent: '-123.456'
currency:
code: EUR
name: European Euro
slug: eur-3b840951-099f-4bd5-90b9-032f7bfe51d9
symbol: €
eligibility_questionnaire:
is_blocking: true
questions:
question_key1: This is the label of the question
question_key2: This is another question label
responses:
question_key1: 'yes'
question_key2: 'no'
slug: fd32b683-a94a-4496-a0c4-726c088af483
submitted_at: '2021-07-15T18:18:17'
type: contractor_of_record
price:
amount: 2900
final_amount: 2610
product:
description: EOR Monthly
features:
- Feature 1
- Feature 2
frequency: monthly
name: EOR Monthly
short_name: EOR
tier: standard
total_amount: 5800
total_discount: 1000
total_in_advance: 2800
total_prorated: 3000
properties:
data:
items:
$ref: '#/components/schemas/ContractorSubscriptions.Summary'
type: array
required:
- data
title: ContractorSubscriptionSummariesResponse
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
IndexCorTerminationRequestsResponse:
description: Response schema listing many termination_requests
example:
current_page: 1
termination_requests:
- cancelled_at: null
employment_deactivation_date: '2026-04-07'
employment_id: c0a167b8-459d-4e96-9766-7a04c160892e
executed_at: '2026-04-07T10:00:00Z'
id: c0a167b8-459d-4e96-9766-7a04c160892e
initiated_at: '2026-03-16T08:00:00Z'
status: executed
termination_date: '2026-03-16'
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
termination_requests:
items:
$ref: '#/components/schemas/CorTerminationRequest'
type: array
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
type: object
title: IndexCorTerminationRequestsResponse
type: object
SuccessResponse:
description: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
example:
data:
status: ok
properties:
data:
properties:
status:
description: The result status. Always `"ok"` for successful operations.
type: string
type: object
required:
- data
title: SuccessResponse
type: object
DateTime:
description: UTC date time in YYYY-MM-DDTHH:mm:ss format
example: '2021-07-15T18:18:17'
format: datetime
title: DateTime
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
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
BadRequestResponse:
description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
example:
message: invalid {resource}
oneOf:
- properties:
message:
description: A human-readable error message describing what was wrong with the request.
type: string
required:
- message
type: object
- properties:
message:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
type: object
title: BadRequestResponse
type: object
CorTerminationRequestCreatedResponse:
example:
data:
employment_deactivation_date: '2026-04-07'
id: c0a167b8-459d-4e96-9766-7a04c160892e
status: initiated
termination_date: '2026-03-16'
properties:
data:
additionalProperties: false
properties:
employment_deactivation_date:
description: The date on which the contractor employment will be deactivated.
format: date
nullable: true
type: string
id:
description: Unique identifier of the termination request.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
status:
description: Current status of the termination request.
enum:
- initiated
- executed
- cancelled
type: string
termination_date:
description: The date when the termination was initiated.
format: date
nullable: true
type: string
required:
- id
- status
- termination_date
- employment_deactivation_date
type: object
required:
- data
title: CorTerminationRequestCreatedResponse
type: object
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
Product:
additionalProperties: false
description: A Remote product offering (e.g., EOR, Contractor Management) with its tier and billing frequency.
example:
description: EOR Monthly
features:
- Feature 1
- Feature 2
frequency: monthly
name: EOR Monthly
short_name: EOR
tier: standard
properties:
description:
description: A description of the product.
type: string
features:
description: Features included in this product tier.
items:
type: string
type: array
frequency:
description: The billing frequency (e.g., "monthly", "annually").
type: string
identifier:
description: A unique machine-readable identifier for this product.
type: string
name:
description: The full product name (e.g., "EOR Monthly").
type: string
short_name:
description: A short display name for the product (e.g., "EOR").
type: string
tier:
description: The product tier (e.g., "standard", "premium").
type: string
required:
- name
- tier
- frequency
title: Product
type: object
ForbiddenResponse:
description: Returned when the authenticated user or token does not have permission to perform the requested action. Check that the token has the required OAuth2 scopes and that the user has the necessary role.
example:
message: Forbidden
properties:
message:
pattern: Forbidden
type: string
required:
- message
title: ForbiddenResponse
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-subscriptions-api-openapi.yml