Oyster HR

Global employment platform

docs.oysterhr.com/reference ↗

Version

OpenAPI

3.0.1

Endpoints

Schemas

Updated

3 days ago

Hr hr global-employment remote-work

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.oysterhr.com

Authentication

bearer

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Company 1 endpoints

GET /v1/company Retrieve company details

Returns details about the connected company

operationId: Company_detailsRetrieve

Responses

200 Successful

401 an invalid access token

GET /v1/company

Departments 1 endpoints

GET /v1/departments Retrieve all departments

Returns a list of departments

operationId: Departments_getAll

Parameters

Name	In	Required	Type	Description
per_page	query	optional	integer
page	query	optional	integer

Responses

200 Successful

401 an invalid access token

GET /v1/departments

Engagements 2 endpoints

GET /v1/engagements Retrieve all engagements

Returns a list of engagements

operationId: Engagements_getAll

Parameters

Name	In	Required	Type	Description
per_page	query	optional	integer
page	query	optional	integer

Responses

200 Successful

401 an invalid access token

GET /v1/engagements

GET /v1/engagements/{id} Retrieve an individual engagement

Returns details for an engagement with a given engagement ID.

operationId: Engagements_getById

Parameters

Name	In	Required	Type	Description
id	path	required	string	Engagement ID

Responses

200 Successful

404 Resource does not exist, or no permission to access resource

GET /v1/engagements/{id}

Expenses 1 endpoints

GET /v1/expenses/{id} Retrieve an individual expense

Returns details for an expense with a given expense ID.

operationId: Expenses_getById

Parameters

Name	In	Required	Type	Description
id	path	required	string	Expense ID

Responses

200 Successful

404 Resource does not exist, or no permission to access resource

GET /v1/expenses/{id}

Operations 1 endpoints

GET /v1/meta/operations/{operation_key} Retrieve an operation

Returns details for an operation with a given operation key.

operationId: Operations_getByOperationKey

Parameters

Name	In	Required	Type	Description
operation_key	path	required	string	Operation key

Responses

200 Successful

404 Resource does not exist, or no permission to access resource

GET /v1/meta/operations/{operation_key}

Payroll 2 endpoints

GET /v1/payroll Retrieve all payroll

Returns a list of payrolls

operationId: Payroll_getAllPayrolls

Parameters

Name	In	Required	Type
per_page	query	optional	integer
page	query	optional	integer
from	query	optional	string
to	query	optional	string
include_records	query	optional	boolean

Responses

200 Successful

401 an invalid access token

GET /v1/payroll

GET /v1/payroll/{id} Retrieve an individual payroll

Returns details for a payroll with a given payroll ID.

operationId: Payroll_getById

Parameters

Name	In	Required	Type	Description
id	path	required	string	Payroll ID

Responses

200 Successful

404 Resource does not exist, or no permission to access resource

GET /v1/payroll/{id}

Time off 3 endpoints

GET /v1/time_off/entitlements Retrieve entitlements

Returns entitlements for each engagement of the company.

operationId: TimeOff_getEntitlements

Parameters

Name	In	Required	Type	Description
per_page	query	optional	integer
page	query	optional	integer

Responses

200 Successful

401 an invalid access token

GET /v1/time_off/entitlements

GET /v1/time_off/requests Retrieve all requests

Returns all Time Off Requests for a company.

operationId: TimeOff_getAllRequests

Parameters

Name	In	Required	Type	Description
per_page	query	optional	integer
page	query	optional	integer

Responses

200 Successful

401 an invalid access token

GET /v1/time_off/requests

GET /v1/time_off/requests/{id} Retrieve an individual request

Returns details for a request.

operationId: TimeOff_getRequest

Parameters

Name	In	Required	Type	Description
id	path	required	string	Time Off Request ID

Responses

200 Successful

401 an invalid access token

404 Resource does not exist, or no permission to access resource

GET /v1/time_off/requests/{id}

Schemas

object AuthenticationCreateAccessTokenRequest

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "example": "1234ABCD",
      "description": "The code is required when requesting an `authorization_code`."
    },
    "client_id": {
      "type": "string",
      "example": "1234ABCD",
      "description": "The client_id of your Developer App. This can be found by visting https://app.oysterhr.com/developer"
    },
    "grant_type": {
      "type": "string",
      "example": "authorization_code",
      "description": "First you need to request an `authorization_code`. Afterwards you can request a `refresh_token`."
    },
    "redirect_uri": {
      "type": "string",
      "example": "https://example.com/inbound",
      "description": "The redirect_uri is required when requesting an `authorization_code`."
    },
    "client_secret": {
      "type": "string",
      "example": "1234ABCD",
      "description": "The secret of your Developer App."
    },
    "refresh_token": {
      "type": "string",
      "example": "https://example.com/inbound",
      "description": "A `refresh_token` is required when requesting a `refresh_token`. A `refresh_token` will be provided when requesting an `authorization_code`"
    }
  }
}

object CompanyDetailsRetrieveResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/company"
    }
  }
}

object DepartmentsGetAllResponse

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/departments"
    },
    "meta": {
      "$ref": "#/components/schemas/meta"
    }
  }
}

object EngagementsGetAllResponse

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/engagements"
    },
    "meta": {
      "$ref": "#/components/schemas/meta"
    }
  }
}

object EngagementsGetByIdResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/engagement"
    }
  }
}

object ExpensesCreateOperationKeyRequest

{
  "type": "object",
  "required": [
    "engagementId",
    "name",
    "incurredOn",
    "category",
    "receiptUrl",
    "receiptAmount"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "category": {
      "type": "string",
      "minLength": 1
    },
    "incurredOn": {
      "type": "string",
      "format": "date",
      "minLength": 1
    },
    "receiptUrl": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "engagementId": {
      "type": "string",
      "minLength": 1
    },
    "receiptAmount": {
      "type": "object",
      "required": [
        "decimal",
        "currencyCode"
      ],
      "properties": {
        "decimal": {
          "type": "string",
          "minLength": 1
        },
        "currencyCode": {
          "type": "string",
          "minLength": 1
        }
      }
    }
  }
}

object ExpensesDeclineExpenseRequest

{
  "type": "object",
  "properties": {
    "reason": {
      "type": "string"
    }
  }
}

object ExpensesGetByIdResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/expense"
    }
  }
}

object OperationsGetByOperationKeyResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/operation"
    }
  }
}

object PayrollGetAllPayrollsResponse

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/payrolls"
    },
    "meta": {
      "$ref": "#/components/schemas/meta"
    }
  }
}

object PayrollGetByIdResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/payroll"
    }
  }
}

object TimeOffGetAllRequestsResponse

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/timeOffRequests"
    },
    "meta": {
      "$ref": "#/components/schemas/meta"
    }
  }
}

object TimeOffGetEntitlementsResponse

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/timeOffEntitlements"
    },
    "meta": {
      "$ref": "#/components/schemas/meta"
    }
  }
}

object TimeOffGetRequestResponse

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/timeOffRequest"
    }
  }
}

object TimeOffRejectRequestRequest

{
  "type": "object",
  "required": [
    "reason"
  ],
  "properties": {
    "reason": {
      "type": "string"
    }
  }
}

object Token

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "example": "read"
    },
    "created_at": {
      "type": "number",
      "example": 167474949830
    },
    "expires_in": {
      "type": "number",
      "example": 7200
    },
    "token_type": {
      "type": "string",
      "example": "Bearer"
    },
    "access_token": {
      "type": "string",
      "example": "1234ABCD"
    },
    "refresh_token": {
      "type": "string",
      "example": "1234ABCD"
    }
  }
}

object address

{
  "type": "object",
  "required": [
    "addressId",
    "addressLine1",
    "postalCode"
  ],
  "properties": {
    "city": {
      "type": "string",
      "nullable": true
    },
    "region": {
      "type": "string",
      "nullable": true
    },
    "addressId": {
      "type": "string"
    },
    "postalCode": {
      "type": "string",
      "nullable": true
    },
    "countryCode": {
      "type": "string",
      "nullable": true
    },
    "addressLine1": {
      "type": "string",
      "nullable": true
    },
    "addressLine2": {
      "type": "string",
      "nullable": true
    }
  }
}

object amount

{
  "type": "object",
  "required": [
    "decimal",
    "currencyCode"
  ],
  "properties": {
    "decimal": {
      "type": "string",
      "pattern": "^\\d+([.]\\d+)?$"
    },
    "currencyCode": {
      "type": "string",
      "maxLength": 3,
      "minLength": 3
    }
  }
}

object asyncResponse

{
  "type": "object",
  "properties": {
    "meta": {
      "type": "object",
      "properties": {
        "operationKey": {
          "type": "string"
        }
      }
    }
  }
}

object company

{
  "type": "object",
  "required": [
    "companyId",
    "name",
    "registrationNumber",
    "addresses"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "addresses": {
      "type": "object",
      "properties": {
        "billingAddress": {
          "$ref": "#/components/schemas/address",
          "type": "object",
          "nullable": true
        },
        "corporateAddress": {
          "$ref": "#/components/schemas/address",
          "type": "object",
          "nullable": true
        }
      }
    },
    "companyId": {
      "type": "string"
    },
    "registrationNumber": {
      "type": "string"
    }
  }
}

object department

{
  "type": "object",
  "required": [
    "departmentId",
    "name",
    "description",
    "engagementsCount"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string",
      "nullable": true
    },
    "departmentId": {
      "type": "string"
    },
    "engagementsCount": {
      "type": "integer"
    }
  }
}

array departments

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/department"
  }
}

object engagement

{
  "type": "object",
  "required": [
    "engagementId",
    "engagementType",
    "personalDetails",
    "startDate",
    "countryCode",
    "role"
  ],
  "properties": {
    "role": {
      "type": "string"
    },
    "state": {
      "type": "string"
    },
    "contract": {
      "type": "object",
      "nullable": true
    },
    "startDate": {
      "type": "string",
      "format": "date"
    },
    "department": {
      "type": "object",
      "nullable": true,
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "departmentId": {
          "type": "string"
        }
      }
    },
    "employment": {
      "type": "object",
      "nullable": true
    },
    "modifiedAt": {
      "type": "string",
      "format": "date-time"
    },
    "countryCode": {
      "type": "string"
    },
    "engagementId": {
      "type": "string"
    },
    "terminations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string"
          },
          "proposedDate": {
            "type": "string",
            "format": "date"
          }
        }
      }
    },
    "engagementType": {
      "enum": [
        "EMPLOYMENT",
        "CONTRACT"
      ],
      "type": "string"
    },
    "personalDetails": {
      "type": "object",
      "required": [
        "name",
        "addresses"
      ],
      "properties": {
        "name": {
          "type": "string",
          "nullable": true
        },
        "addresses": {
          "type": "object",
          "properties": {
            "livingAddress": {
              "$ref": "#/components/schemas/address",
              "type": "object",
              "nullable": true
            },
            "mailingAddress": {
              "$ref": "#/components/schemas/address",
              "type": "object",
              "nullable": true
            }
          }
        },
        "dateOfBirth": {
          "type": "string",
          "nullable": true
        },
        "citizenships": {
          "type": "array",
          "items": {
            "type": "string",
            "nullable": true
          }
        },
        "phoneNumbers": {
          "type": "object",
          "properties": {
            "default": {
              "$ref": "#/components/schemas/phoneNumber",
              "type": "object",
              "nullable": true
            },
            "emergency": {
              "$ref": "#/components/schemas/phoneNumber",
              "type": "object",
              "nullable": true
            }
          }
        }
      }
    },
    "benefitEnrollments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "plan": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string"
              },
              "descriptiveName": {
                "type": "string"
              }
            }
          },
          "state": {
            "type": "string"
          },
          "benefitEnrollmentId": {
            "type": "string"
          }
        }
      }
    }
  }
}

array engagements

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/engagement"
  }
}

object error

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

object errors

{
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

object expense

{
  "type": "object",
  "required": [
    "expenseId",
    "name",
    "amount",
    "category",
    "receiptAmount"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "amount": {
      "$ref": "#/components/schemas/amount",
      "type": "object"
    },
    "source": {
      "type": "string"
    },
    "category": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "expenseId": {
      "type": "string"
    },
    "engagement": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "nullable": true
        },
        "engagementId": {
          "type": "string"
        },
        "engagementType": {
          "type": "string",
          "pattern": "^[A-Z_]+$"
        }
      }
    },
    "incurredOn": {
      "type": "string",
      "format": "date"
    },
    "receiptUrl": {
      "type": "string",
      "format": "uri",
      "nullable": true
    },
    "reviewedAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "description": {
      "type": "string",
      "nullable": true
    },
    "reviewState": {
      "type": "string"
    },
    "submittedAt": {
      "type": "string",
      "format": "date-time"
    },
    "receiptAmount": {
      "$ref": "#/components/schemas/amount",
      "type": "object"
    }
  }
}

array expenses

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/expense"
  }
}

object fieldErrors

{
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

object meta

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer"
    },
    "count": {
      "type": "integer"
    },
    "items": {
      "type": "integer"
    },
    "pages": {
      "type": "integer"
    },
    "lastUrl": {
      "type": "string"
    },
    "nextUrl": {
      "type": "string"
    },
    "pageUrl": {
      "type": "string"
    },
    "prevUrl": {
      "type": "string"
    },
    "firstUrl": {
      "type": "string"
    }
  }
}

object operation

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object"
    },
    "meta": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "completed": {
          "type": "boolean"
        }
      }
    },
    "request": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "queryParams": {
          "type": "object"
        },
        "responseCode": {
          "type": "integer"
        }
      }
    }
  }
}

object payroll

{
  "type": "object",
  "required": [
    "payrollId",
    "currencyCode",
    "cutoffTimeForPayroll",
    "state",
    "payrollRecordsCount"
  ],
  "properties": {
    "state": {
      "type": "string"
    },
    "records": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/payrollRecord"
      }
    },
    "payrollId": {
      "type": "string"
    },
    "currencyCode": {
      "type": "string"
    },
    "payrollRecordsCount": {
      "type": "integer"
    },
    "cutoffTimeForPayroll": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    }
  }
}

object payrollRecord

{
  "type": "object",
  "required": [
    "engagementId",
    "currencyCode",
    "monthlyPaymentsTotalAmount",
    "allowancesTotalAmount",
    "benefitsTotalAmount",
    "bonusesTotalAmount",
    "addOnsTotalAmount",
    "taxesTotalAmount",
    "trueUpsTotalAmount",
    "oysterFeesTotalAmount",
    "engagement"
  ],
  "properties": {
    "engagement": {
      "type": "object",
      "required": [
        "name",
        "cutoffMonthDay",
        "engagementType"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "cutoffMonthDay": {
          "type": "integer"
        },
        "engagementType": {
          "type": "string"
        }
      }
    },
    "currencyCode": {
      "type": "string"
    },
    "engagementId": {
      "type": "string"
    },
    "taxesTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "addOnsTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "bonusesTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "trueUpsTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "benefitsTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "allowancesTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "oysterFeesTotalAmount": {
      "$ref": "#/components/schemas/amount"
    },
    "monthlyPaymentsTotalAmount": {
      "$ref": "#/components/schemas/amount"
    }
  }
}

array payrolls

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/payroll"
  }
}

object phoneNumber

{
  "type": "object",
  "required": [
    "number"
  ],
  "properties": {
    "number": {
      "type": "string"
    },
    "countryCode": {
      "type": "string",
      "nullable": true
    }
  }
}

object timeOffEngagementDetails

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "countryCode": {
      "type": "string"
    },
    "engagementId": {
      "type": "string"
    }
  }
}

array timeOffEntitlements

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "taken": {
        "type": "number",
        "format": "float"
      },
      "units": {
        "enum": [
          "DAYS"
        ],
        "type": "string"
      },
      "accrued": {
        "type": "number",
        "format": "float"
      },
      "carried": {
        "type": "number",
        "format": "float"
      },
      "upcoming": {
        "type": "number",
        "format": "float"
      },
      "engagement": {
        "$ref": "#/components/schemas/timeOffEngagementDetails"
      },
      "adjustedAdhoc": {
        "type": "number",
        "format": "float"
      },
      "availableBalance": {
        "type": "number",
        "format": "float"
      },
      "projectedBalance": {
        "type": "number",
        "format": "float"
      },
      "annualEntitlement": {
        "type": "number",
        "format": "float"
      }
    }
  }
}

object timeOffRequest

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "state": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "reason": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "endDate": {
      "type": "string",
      "format": "date"
    },
    "startDate": {
      "type": "string",
      "format": "date"
    },
    "engagement": {
      "$ref": "#/components/schemas/timeOffEngagementDetails"
    },
    "periodInHours": {
      "type": "number",
      "format": "float"
    },
    "lastDayDuration": {
      "type": "string",
      "pattern": "^[A-Z_]+$",
      "nullable": true
    },
    "rejectionReason": {
      "type": "string",
      "nullable": true
    },
    "firstDayDuration": {
      "type": "string",
      "pattern": "^[A-Z_]+$"
    },
    "timeOffRequestId": {
      "type": "string"
    },
    "requesterComments": {
      "type": "string",
      "nullable": true
    }
  }
}

array timeOffRequests

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/timeOffRequest"
  }
}