openapi: 3.0.1
info:
title: Endpoints
description: >-
Oyster uses OAuth2 to enable customers to grant access to their data to
third party applications. Customers also need to use this API to
authenticate themselves when making API requests.
version: v1
license:
name: MIT
servers:
- url: https://api.oysterhr.com
tags:
- description: >-
With the Time Off API, you can manage your team's time off requests.
You can approve or decline specific time off requests, access information
about a particular request, and get updates on all time off requests.
It also provides details on time off entitlements for each engagement
within the company
name: Time Off
- description: >-
Expenses API allows you to remotely manage expenses of your team.
Approve or decline a specific expense, get info about a specific expense
or receive real-time information about all expenses.
name: Expenses
- name: Engagements
- name: Payroll
- name: Authentication
- name: Company
- name: Departments
- name: Operations
paths:
/oauth2/token:
post:
tags:
- Authentication
summary: Create an access token
operationId: Authentication_createAccessToken
description: >
Oyster grants access to API resources based on OAuth. This means that
individual customers grant API access to Developer Apps that you create.
This applies to both customers and partners. Follow these simple steps:
1. [Create an Oyster account](https://app.oysterhr.com/sign_up)
or [log in](https://app.oysterhr.com/users/sign_in) to your existing
account.
2. Create an Oyster Developer App in the [Developer
Tab](https://app.oysterhr.com/developer) (If you can't see the developer
tab please contact us to enable it for your account).
Hint: If you
are a customer doing this as a one time action you don't need to specify
a functioning URL as step 3 will explain.
3. If you are a
customer you can simply click on the "Authorization URL" and grant
access to your own app. You will be redirected to the URL you specified
when creating the Developer App. In the URL you will see that
`?code=xxx` has been added to the URL. This is the `code` you need to
create an access token.
If you are a partner add "Authorization URL
to your application. The redirect_url should be a URL that goes back to
your app and you're able to programmatically retrieve the URL query
param of `?code=xxx` to then create an access token.
4. You
need to first request an `authorization_code` with the API request
detailed below. This will provide an `access_token` that is used as the
Bearer Token for making API requests to Oyster. Ensure that you store
the `refresh_token` for making future API requests.
5. If your
`access_token` has expired then request a new one using your
`refresh_token` that you have stored earlier. Ensure you store the new
`refresh_token` each time as the previous ones will expire.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AuthenticationCreateAccessTokenRequest'
responses:
'201':
description: Create an access token to make an API request
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
/v1/expenses/{id}/approve:
post:
tags:
- Expenses
summary: Approve expense
operationId: Expenses_approveExpense
security:
- bearer_auth:
- manage
description: Approves an expense.
parameters:
- description: Expense ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
'403':
description: an invalid OAuth scope
content:
application/json:
examples:
an invalid OAuth scope:
value:
error:
message: Access to this resource requires scope "manage".
schema:
$ref: '#/components/schemas/error'
'404':
description: Resource does not exist, or no permission to access resource
'422':
description: Operation cannot be performed
content:
application/json:
examples:
Operation cannot be performed:
value:
errors:
- message: Expense has been approved already
schema:
$ref: '#/components/schemas/errors'
/v1/expenses/{id}/decline:
post:
tags:
- Expenses
summary: Decline expense
operationId: Expenses_declineExpense
security:
- bearer_auth:
- manage
description: Declines an expense.
parameters:
- description: Expense ID
name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExpensesDeclineExpenseRequest'
examples:
Successful:
summary: Successful
value:
reason: exceeds budget for this period
responses:
'200':
description: Successful
'403':
description: an invalid OAuth scope
content:
application/json:
examples:
an invalid OAuth scope:
value:
error:
message: Access to this resource requires scope "manage".
schema:
$ref: '#/components/schemas/error'
'404':
description: Resource does not exist, or no permission to access resource
'422':
description: Operation cannot be performed
content:
application/json:
examples:
Operation cannot be performed:
value:
errors:
- message: Expense has been declined already
schema:
$ref: '#/components/schemas/errors'
/v1/expenses/{id}:
get:
tags:
- Expenses
summary: Retrieve an individual expense
operationId: Expenses_getById
security:
- bearer_auth:
- read
description: Returns details for an expense with a given expense ID.
parameters:
- description: Expense ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
description: >-
Quia amet incidunt. Deleniti odit et. Repellendus id
harum.
expenseId: zxbhh9d8
name: Thanksgiving Volcano coffee
amount:
decimal: '631.87'
currencyCode: EUR
category: CAR
incurredOn: '2022-10-15'
submittedAt: '2022-10-15T12:34:56Z'
reviewState: UNREVIEWED
reviewedAt: null
receiptAmount:
decimal: '631.87'
currencyCode: USD
receiptUrl: null
engagement:
engagementId: SsvwPW9p
name: null
engagementType: EMPLOYMENT
source: OYSTER
schema:
$ref: '#/components/schemas/ExpensesGetByIdResponse'
'404':
description: Resource does not exist, or no permission to access resource
/v1/expenses:
post:
tags:
- Expenses
summary: Create expense
operationId: Expenses_createOperationKey
security:
- bearer_auth:
- manage
description: >-
Creates a new expense for an engagement. This is an asynchronous
operation. Returns operationKey that can be used to retrieve the
operation to know if it's successfully completed
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExpensesCreateOperationKeyRequest'
examples:
Successfully created async operation:
summary: Successfully created async operation
value:
description: ''
engagementId: Xse7pSwV
name: An expense
category: HOME_OFFICE
incurredOn: '2022-10-15'
receiptAmount:
decimal: '1.23'
currencyCode: GBP
receiptUrl: https://www.example.com/receipts/test.pdf
responses:
'202':
description: Successfully created async operation
content:
application/json:
examples:
Successfully created async operation:
value:
meta:
operationKey: 5702f2db-6f1c-4da3-9b16-414dad0271ee
schema:
$ref: '#/components/schemas/asyncResponse'
'400':
description: improperly structured JSON
content:
application/json:
examples:
improperly structured JSON:
value:
errors:
- field: engagementId
message: Engagement id is in invalid format
- field: name
message: Name must be filled
- field: incurredOn
message: Incurred on must be a date
- field: category
message: Category is in invalid format
- field: receiptUrl
message: Receipt url is in invalid format
- field: receiptAmount.decimal
message: Receipt amount decimal must be a string
- field: receiptAmount.currencyCode
message: Receipt amount currency code is in invalid format
schema:
$ref: '#/components/schemas/fieldErrors'
'403':
description: an invalid OAuth scope
content:
application/json:
examples:
an invalid OAuth scope:
value:
error:
message: Access to this resource requires scope "manage".
schema:
$ref: '#/components/schemas/error'
'422':
description: Unprocessable entity
content:
application/json:
examples:
Unprocessable entity:
value:
errors:
- message: Category must have a valid category
schema:
$ref: '#/components/schemas/fieldErrors'
/v1/company:
get:
tags:
- Company
summary: Retrieve company details
operationId: Company_detailsRetrieve
security:
- bearer_auth:
- read
description: Returns details about the connected company
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
companyId: uPeGkqOp
name: company 00035 name
registrationNumber: S4866459C
addresses:
corporateAddress:
addressId: KgmrAgaO
addressLine1: 448 Bernita Locks
addressLine2: Autumn Crossing
city: New Leshastad
region: OK
countryCode: CA
postalCode: '64367'
billingAddress:
addressId: RvXZpmBP
addressLine1: 317 Isiah Passage
addressLine2: Eagle Place
city: Kerlukehaven
region: UT
countryCode: AU
postalCode: 91386-6007
schema:
$ref: '#/components/schemas/CompanyDetailsRetrieveResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/v1/departments:
get:
tags:
- Departments
summary: Retrieve all departments
operationId: Departments_getAll
security:
- bearer_auth:
- read
description: Returns a list of departments
parameters:
- name: per_page
in: query
required: false
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
responses:
'200':
description: Successful
content:
application/json:
examples:
No departments:
value:
data: []
meta:
items: 100
count: 0
page: 1
pages: 1
firstUrl: /v1/departments?perPage=100&page=1
lastUrl: /v1/departments?perPage=100&page=1
pageUrl: /v1/departments?perPage=100&page=1
nextUrl: /v1/departments?perPage=100&page=
prevUrl: /v1/departments?perPage=100&page=
Successful:
value:
data:
- description: >-
Listicle authentic fingerstache paleo kombucha
shoreditch yr.
departmentId: V5PNwnEh
name: Health & Beauty
engagementsCount: 0
- description: >-
Kale chips slow-carb tote bag tofu portland 3 wolf
moon bespoke letterpress.
departmentId: MK0nqu2W
name: Toys
engagementsCount: 0
- description: Taxidermy meh try-hard yr echo waistcoat ramps ennui.
departmentId: f2I3ilRT
name: Outdoors & Grocery
engagementsCount: 0
- description: >-
Yolo vhs xoxo park blue bottle artisan sustainable
polaroid.
departmentId: NyEkcAoV
name: Toys & Sports
engagementsCount: 0
- description: >-
Post-ironic typewriter irony church-key food truck
cardigan.
departmentId: dTOzpd6Y
name: Outdoors
engagementsCount: 0
meta:
items: 100
count: 5
page: 1
pages: 1
firstUrl: /v1/departments?perPage=100&page=1
lastUrl: /v1/departments?perPage=100&page=1
pageUrl: /v1/departments?perPage=100&page=1
nextUrl: /v1/departments?perPage=100&page=
prevUrl: /v1/departments?perPage=100&page=
schema:
$ref: '#/components/schemas/DepartmentsGetAllResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/v1/engagements/{id}:
get:
tags:
- Engagements
summary: Retrieve an individual engagement
operationId: Engagements_getById
security:
- bearer_auth:
- read
description: Returns details for an engagement with a given engagement ID.
parameters:
- description: Engagement ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
engagementId: uxiFbbaK
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: EMPLOYMENT
state: DRAFT
role: Principal Technology Planner
countryCode: CW
personalDetails:
name: Laurette Anderson
addresses:
livingAddress: null
mailingAddress: null
employment:
employmentId: uxiFbbaK
fullLegalName: null
email: null
employmentType: null
lastDayOn: null
salary:
decimal: '12345.00'
currencyCode: EUR
contract: null
benefitEnrollments: []
terminations: []
department: null
schema:
$ref: '#/components/schemas/EngagementsGetByIdResponse'
'404':
description: Resource does not exist, or no permission to access resource
/v1/engagements:
get:
tags:
- Engagements
summary: Retrieve all engagements
operationId: Engagements_getAll
security:
- bearer_auth:
- read
description: Returns a list of engagements
parameters:
- name: per_page
in: query
required: false
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
responses:
'200':
description: Successful
content:
application/json:
examples:
No engagements:
value:
data: []
meta:
items: 100
count: 0
page: 1
pages: 1
firstUrl: /v1/engagements?perPage=100&page=1
lastUrl: /v1/engagements?perPage=100&page=1
pageUrl: /v1/engagements?perPage=100&page=1
nextUrl: /v1/engagements?perPage=100&page=
prevUrl: /v1/engagements?perPage=100&page=
Successful:
value:
data:
- engagementId: 2ug3WBT0
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: EMPLOYMENT
state: DRAFT
role: Banking Supervisor Consultant
countryCode: MF
personalDetails:
name: null
addresses:
livingAddress: null
mailingAddress: null
livingAddress: null
mailingAddress: null
employment:
employmentId: 2ug3WBT0
name: Rep Melda Stark
fullLegalName: Rep Melda Stark
email: james.treutel@mayer.test
employmentType: null
lastDayOn: null
salarySubunit: 1234500
salaryCurrencyCode: EUR
salary:
decimal: '12345.00'
currencyCode: EUR
contract: null
benefitEnrollments: []
terminations: []
department: null
usefulInfo: null
- engagementId: AVT7lRbj
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: EMPLOYMENT
state: DRAFT
role: Corporate Manufacturing Liaison Consultant
countryCode: NZ
personalDetails:
name: null
addresses:
livingAddress: null
mailingAddress: null
livingAddress: null
mailingAddress: null
employment:
employmentId: AVT7lRbj
name: Winston Breitenberg
fullLegalName: Winston Breitenberg
email: estrella.tromp@green-greenfelder.test
employmentType: null
lastDayOn: null
salarySubunit: 1234500
salaryCurrencyCode: EUR
salary:
decimal: '12345.00'
currencyCode: EUR
contract: null
benefitEnrollments: []
terminations: []
department: null
usefulInfo: null
- engagementId: yBY8ab5n
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: EMPLOYMENT
state: DRAFT
role: Education Manager Consultant
countryCode: UG
personalDetails:
name: null
addresses:
livingAddress: null
mailingAddress: null
livingAddress: null
mailingAddress: null
employment:
employmentId: yBY8ab5n
name: Delia Ward
fullLegalName: Delia Ward
email: shawn.bauch@kerluke.test
employmentType: null
lastDayOn: null
salarySubunit: 1234500
salaryCurrencyCode: EUR
salary:
decimal: '12345.00'
currencyCode: EUR
contract: null
benefitEnrollments: []
terminations: []
department: null
usefulInfo: null
- engagementId: VVlXNYcy
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: CONTRACT
state: IN_PROGRESS
role: Future Specialist Consultant
countryCode: MG
personalDetails:
name: Henry Reichert
addresses:
livingAddress: null
mailingAddress: null
livingAddress: null
mailingAddress: null
employment: null
contract:
contractId: VVlXNYcy
name: Bethanie Turcotte
email: song@wiegand-ledner.test
billingType: FIXED
taxIdNumber: null
benefitEnrollments: []
terminations: []
department: null
usefulInfo: null
- engagementId: kUhg4dS4
modifiedAt: '2022-10-15T12:34:56Z'
startDate: '2022-10-15'
engagementType: CONTRACT
state: IN_PROGRESS
role: Customer Banking Strategist Consultant
countryCode: HK
personalDetails:
name: Anibal Bins
addresses:
livingAddress: null
mailingAddress: null
livingAddress: null
mailingAddress: null
employment: null
contract:
contractId: kUhg4dS4
name: Mr. Ronnie Klocko
email: irvin.medhurst@mohr.example
billingType: FIXED
taxIdNumber: null
benefitEnrollments: []
terminations: []
department: null
meta:
items: 100
count: 5
page: 1
pages: 1
firstUrl: /v1/engagements?perPage=100&page=1
lastUrl: /v1/engagements?perPage=100&page=1
pageUrl: /v1/engagements?perPage=100&page=1
nextUrl: /v1/engagements?perPage=100&page=
prevUrl: /v1/engagements?perPage=100&page=
schema:
$ref: '#/components/schemas/EngagementsGetAllResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/v1/meta/operations/{operation_key}:
get:
tags:
- Operations
summary: Retrieve an operation
operationId: Operations_getByOperationKey
security:
- bearer_auth:
- read
description: Returns details for an operation with a given operation key.
parameters:
- description: Operation key
name: operation_key
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
request:
method: GET
path: /resources
queryParams:
foo: bar
responseCode: 200
data:
foo: bar
bar: baz
meta:
completed: true
success: true
schema:
$ref: '#/components/schemas/OperationsGetByOperationKeyResponse'
'404':
description: Resource does not exist, or no permission to access resource
/v1/payroll/{id}:
get:
tags:
- Payroll
summary: Retrieve an individual payroll
operationId: Payroll_getById
security:
- bearer_auth:
- read
description: Returns details for a payroll with a given payroll ID.
parameters:
- description: Payroll ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
payrollId: UmTDnTUV
currencyCode: USD
cutoffTimeForPayroll: '2022-10-07T05:00:00.000Z'
state: DRAFT
payrollRecordsCount: 2
records:
- engagementId: CjVBtL3E
currencyCode: EUR
monthlyPaymentsTotalAmount:
decimal: '0.00'
currencyCode: USD
allowancesTotalAmount:
decimal: '0.00'
currencyCode: USD
benefitsTotalAmount:
decimal: '0.00'
currencyCode: USD
bonusesTotalAmount:
decimal: '0.00'
currencyCode: USD
addOnsTotalAmount:
decimal: '0.00'
currencyCode: USD
taxesTotalAmount:
decimal: '0.00'
currencyCode: USD
trueUpsTotalAmount:
decimal: '0.00'
currencyCode: USD
oysterFeesTotalAmount:
decimal: '0.00'
currencyCode: USD
engagement:
name: Georgeann Hintz
cutoffMonthDay: 6
engagementType: EMPLOYMENT
- engagementId: R73L6T8L
currencyCode: EUR
monthlyPaymentsTotalAmount:
decimal: '0.00'
currencyCode: USD
allowancesTotalAmount:
decimal: '0.00'
currencyCode: USD
benefitsTotalAmount:
decimal: '0.00'
currencyCode: USD
bonusesTotalAmount:
decimal: '0.00'
currencyCode: USD
addOnsTotalAmount:
decimal: '0.00'
currencyCode: USD
taxesTotalAmount:
decimal: '0.00'
currencyCode: USD
trueUpsTotalAmount:
decimal: '0.00'
currencyCode: USD
oysterFeesTotalAmount:
decimal: '0.00'
currencyCode: USD
engagement:
name: Msgr Floyd Streich
cutoffMonthDay: 6
engagementType: EMPLOYMENT
schema:
$ref: '#/components/schemas/PayrollGetByIdResponse'
'404':
description: Resource does not exist, or no permission to access resource
/v1/payroll:
get:
tags:
- Payroll
summary: Retrieve all payroll
operationId: Payroll_getAllPayrolls
security:
- bearer_auth:
- read
description: Returns a list of payrolls
parameters:
- name: per_page
in: query
required: false
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
- name: from
in: query
required: false
schema:
type: string
- name: to
in: query
required: false
schema:
type: string
- name: include_records
in: query
required: false
schema:
type: boolean
responses:
'200':
description: Successful
content:
application/json:
examples:
No payrolls:
value:
data: []
meta:
items: 100
count: 0
page: 1
pages: 1
firstUrl: /v1/payroll?perPage=100&page=1&from=&to=&includeRecords=
lastUrl: /v1/payroll?perPage=100&page=1&from=&to=&includeRecords=
pageUrl: /v1/payroll?perPage=100&page=1&from=&to=&includeRecords=
nextUrl: /v1/payroll?perPage=100&page=&from=&to=&includeRecords=
prevUrl: /v1/payroll?perPage=100&page=&from=&to=&includeRecords=
Successful:
value:
data:
- payrollId: abw0ovv2
currencyCode: USD
cutoffTimeForPayroll: '2022-10-07T05:00:00.000Z'
state: DRAFT
payrollRecordsCount: 2
- payrollId: ED6xssq7
currencyCode: USD
cutoffTimeForPayroll: '2022-10-07T05:00:00.000Z'
state: DRAFT
payrollRecordsCount: 2
meta:
items: 100
count: 2
page: 1
pages: 1
firstUrl: >-
/v1/payroll?perPage=100&page=1&from=2023-03&to=2023-04&includeRecords=
lastUrl: >-
/v1/payroll?perPage=100&page=1&from=2023-03&to=2023-04&includeRecords=
pageUrl: >-
/v1/payroll?perPage=100&page=1&from=2023-03&to=2023-04&includeRecords=
nextUrl: >-
/v1/payroll?perPage=100&page=&from=2023-03&to=2023-04&includeRecords=
prevUrl: >-
/v1/payroll?perPage=100&page=&from=2023-03&to=2023-04&includeRecords=
schema:
$ref: '#/components/schemas/PayrollGetAllPayrollsResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/v1/time_off/entitlements:
get:
tags:
- Time Off
summary: Retrieve entitlements
operationId: TimeOff_getEntitlements
security:
- bearer_auth:
- read
description: Returns entitlements for each engagement of the company.
parameters:
- name: per_page
in: query
required: false
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
responses:
'200':
description: Successful
content:
application/json:
examples:
No engagements:
value:
data: []
meta:
items: 100
count: 0
page: 1
pages: 1
firstUrl: /v1/time_off/entitlements?perPage=100&page=1
lastUrl: /v1/time_off/entitlements?perPage=100&page=1
pageUrl: /v1/time_off/entitlements?perPage=100&page=1
nextUrl: /v1/time_off/entitlements?perPage=100&page=
prevUrl: /v1/time_off/entitlements?perPage=100&page=
Successful:
value:
data:
- engagement:
engagementId: AaaEAOPo
name: Brad Doe
type: EMPLOYMENT
countryCode: GB
annualEntitlement: 30
accrued: 30
carried: 0
adjustedAdhoc: 0
taken: 0
availableBalance: 29
upcoming: 0
projectedBalance: 29
units: DAYS
- engagement:
engagementId: vPiWNX7X
name: John Mark
type: EMPLOYMENT
countryCode: GB
annualEntitlement: 24.5
accrued: 24.5
carried: 0
adjustedAdhoc: 0
taken: 0
availableBalance: 24.5
upcoming: 0
projectedBalance: 24.5
units: DAYS
meta:
items: 100
count: 2
page: 1
pages: 1
firstUrl: /v1/time_off/entitlements?perPage=100&page=1
lastUrl: /v1/time_off/entitlements?perPage=100&page=1
pageUrl: /v1/time_off/entitlements?perPage=100&page=1
nextUrl: /v1/time_off/entitlements?perPage=100&page=
prevUrl: /v1/time_off/entitlements?perPage=100&page=
schema:
$ref: '#/components/schemas/TimeOffGetEntitlementsResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/v1/time_off/requests/{id}/approve:
post:
tags:
- Time Off
summary: Approve request
operationId: TimeOff_approveRequest
security:
- bearer_auth:
- manage
description: Approves a time off request.
parameters:
- description: Time Off Request ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
'403':
description: an invalid OAuth scope
content:
application/json:
examples:
an invalid OAuth scope:
value:
error:
message: Access to this resource requires scope "manage".
schema:
$ref: '#/components/schemas/error'
'404':
description: Resource does not exist, or no permission to access resource
'422':
description: Operation cannot be performed
content:
application/json:
examples:
Operation cannot be performed:
value:
errors:
- message: Can't approve a request that's in the APPROVED state
schema:
$ref: '#/components/schemas/errors'
/v1/time_off/requests/{id}/reject:
post:
tags:
- Time Off
summary: Reject request
operationId: TimeOff_rejectRequest
security:
- bearer_auth:
- manage
description: Rejects a time off request.
parameters:
- description: Time Off Request ID
name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOffRejectRequestRequest'
examples:
Successful:
summary: Successful
value:
reason: We need you!
responses:
'200':
description: Successful
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
'403':
description: an invalid OAuth scope
content:
application/json:
examples:
an invalid OAuth scope:
value:
error:
message: Access to this resource requires scope "manage".
schema:
$ref: '#/components/schemas/error'
'404':
description: Resource does not exist, or no permission to access resource
'422':
description: Operation cannot be performed
content:
application/json:
examples:
Operation cannot be performed:
value:
errors:
- message: Can't reject a request that's in the REJECTED state
schema:
$ref: '#/components/schemas/errors'
/v1/time_off/requests/{id}:
get:
tags:
- Time Off
summary: Retrieve an individual request
operationId: TimeOff_getRequest
security:
- bearer_auth:
- read
description: Returns details for a request.
parameters:
- description: Time Off Request ID
name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
timeOffRequestId: 6tkQOMxy
engagement:
engagementId: AhbNxBVN
name: Lizette Paucek
type: EMPLOYMENT
countryCode: PK
startDate: '2022-02-01'
endDate: '2022-02-02'
firstDayDuration: FULL_DAY
lastDayDuration: FULL_DAY
state: SUBMITTED
type: VACATION
requesterComments: Need a rest
rejectionReason: null
reason: PAID_TIME_OFF
periodInHours: 16
schema:
$ref: '#/components/schemas/TimeOffGetRequestResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
'404':
description: Resource does not exist, or no permission to access resource
/v1/time_off/requests:
get:
tags:
- Time Off
summary: Retrieve all requests
operationId: TimeOff_getAllRequests
security:
- bearer_auth:
- read
description: Returns all Time Off Requests for a company.
parameters:
- name: per_page
in: query
required: false
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
responses:
'200':
description: Successful
content:
application/json:
examples:
No requests:
value:
data: []
meta:
items: 100
count: 0
page: 1
pages: 1
firstUrl: /v1/time_off/requests?perPage=100&page=1
lastUrl: /v1/time_off/requests?perPage=100&page=1
pageUrl: /v1/time_off/requests?perPage=100&page=1
nextUrl: /v1/time_off/requests?perPage=100&page=
prevUrl: /v1/time_off/requests?perPage=100&page=
Successful:
value:
data:
- timeOffRequestId: aR1F7cum
engagement:
engagementId: K2HrjqDi
name: Alonso Hyatt
type: EMPLOYMENT
countryCode: LV
startDate: '2022-02-01'
endDate: '2022-02-02'
firstDayDuration: FULL_DAY
lastDayDuration: FULL_DAY
state: SUBMITTED
type: VACATION
requesterComments: Need a rest
rejectionReason: null
reason: PAID_TIME_OFF
periodInHours: 16
- timeOffRequestId: xaQYmvy3
engagement:
engagementId: y9UvCkMi
name: Msgr. Juan Larson
type: EMPLOYMENT
countryCode: GS
startDate: '2022-02-01'
endDate: '2022-02-02'
firstDayDuration: FULL_DAY
lastDayDuration: FULL_DAY
state: SUBMITTED
type: VACATION
requesterComments: Need a rest
rejectionReason: null
reason: PAID_TIME_OFF
periodInHours: 16
- timeOffRequestId: ADyXwhvf
engagement:
engagementId: 2ueHWmjt
name: Shayne Runte
type: EMPLOYMENT
countryCode: NC
startDate: '2022-02-01'
endDate: '2022-02-02'
firstDayDuration: FULL_DAY
lastDayDuration: FULL_DAY
state: SUBMITTED
type: VACATION
requesterComments: Need a rest
rejectionReason: null
reason: PAID_TIME_OFF
periodInHours: 16
meta:
items: 100
count: 3
page: 1
pages: 1
firstUrl: /v1/time_off/requests?perPage=100&page=1
lastUrl: /v1/time_off/requests?perPage=100&page=1
pageUrl: /v1/time_off/requests?perPage=100&page=1
nextUrl: /v1/time_off/requests?perPage=100&page=
prevUrl: /v1/time_off/requests?perPage=100&page=
schema:
$ref: '#/components/schemas/TimeOffGetAllRequestsResponse'
'401':
description: an invalid access token
content:
application/json:
examples:
an invalid access token:
value:
error:
message: The access token is invalid
schema:
$ref: '#/components/schemas/error'
components:
schemas:
Token:
type: object
properties:
access_token:
type: string
example: 1234ABCD
token_type:
type: string
example: Bearer
expires_in:
type: number
example: 7200
refresh_token:
type: string
example: 1234ABCD
scope:
type: string
example: read
created_at:
type: number
example: 167474949830
address:
type: object
properties:
addressId:
type: string
addressLine1:
type: string
nullable: true
addressLine2:
type: string
nullable: true
city:
type: string
nullable: true
region:
type: string
nullable: true
countryCode:
type: string
nullable: true
postalCode:
type: string
nullable: true
required:
- addressId
- addressLine1
- postalCode
amount:
type: object
properties:
decimal:
type: string
pattern: ^\d+([.]\d+)?$
currencyCode:
type: string
minLength: 3
maxLength: 3
required:
- decimal
- currencyCode
phoneNumber:
type: object
properties:
countryCode:
type: string
nullable: true
number:
type: string
required:
- number
company:
type: object
properties:
companyId:
type: string
name:
type: string
registrationNumber:
type: string
addresses:
type: object
properties:
corporateAddress:
type: object
nullable: true
$ref: '#/components/schemas/address'
billingAddress:
type: object
nullable: true
$ref: '#/components/schemas/address'
required:
- companyId
- name
- registrationNumber
- addresses
department:
type: object
properties:
description:
type: string
nullable: true
departmentId:
type: string
name:
type: string
engagementsCount:
type: integer
required:
- departmentId
- name
- description
- engagementsCount
departments:
type: array
items:
$ref: '#/components/schemas/department'
engagement:
type: object
properties:
engagementId:
type: string
modifiedAt:
type: string
format: date-time
startDate:
type: string
format: date
engagementType:
enum:
- EMPLOYMENT
- CONTRACT
type: string
state:
type: string
role:
type: string
countryCode:
type: string
personalDetails:
type: object
properties:
name:
type: string
nullable: true
addresses:
type: object
properties:
livingAddress:
type: object
nullable: true
$ref: '#/components/schemas/address'
mailingAddress:
type: object
nullable: true
$ref: '#/components/schemas/address'
citizenships:
type: array
items:
type: string
nullable: true
dateOfBirth:
type: string
nullable: true
phoneNumbers:
type: object
properties:
default:
type: object
nullable: true
$ref: '#/components/schemas/phoneNumber'
emergency:
type: object
nullable: true
$ref: '#/components/schemas/phoneNumber'
required:
- name
- addresses
employment:
type: object
nullable: true
contract:
type: object
nullable: true
benefitEnrollments:
type: array
items:
type: object
properties:
benefitEnrollmentId:
type: string
plan:
type: object
properties:
provider:
type: string
descriptiveName:
type: string
name:
type: string
state:
type: string
terminations:
type: array
items:
type: object
properties:
state:
type: string
proposedDate:
type: string
format: date
department:
type: object
nullable: true
properties:
description:
type: string
departmentId:
type: string
name:
type: string
required:
- engagementId
- engagementType
- personalDetails
- startDate
- countryCode
- role
engagements:
type: array
items:
$ref: '#/components/schemas/engagement'
expense:
type: object
properties:
description:
type: string
nullable: true
expenseId:
type: string
name:
type: string
amount:
type: object
$ref: '#/components/schemas/amount'
category:
type: string
pattern: ^[A-Z_]+$
incurredOn:
type: string
format: date
submittedAt:
type: string
format: date-time
reviewState:
type: string
reviewedAt:
type: string
nullable: true
format: date-time
receiptAmount:
type: object
$ref: '#/components/schemas/amount'
receiptUrl:
type: string
nullable: true
format: uri
engagement:
type: object
properties:
engagementId:
type: string
name:
type: string
nullable: true
engagementType:
type: string
pattern: ^[A-Z_]+$
source:
type: string
required:
- expenseId
- name
- amount
- category
- receiptAmount
expenses:
type: array
items:
$ref: '#/components/schemas/expense'
payroll:
type: object
properties:
payrollId:
type: string
currencyCode:
type: string
cutoffTimeForPayroll:
type: string
format: date-time
nullable: true
state:
type: string
payrollRecordsCount:
type: integer
records:
type: array
items:
$ref: '#/components/schemas/payrollRecord'
required:
- payrollId
- currencyCode
- cutoffTimeForPayroll
- state
- payrollRecordsCount
payrollRecord:
type: object
properties:
engagementId:
type: string
currencyCode:
type: string
monthlyPaymentsTotalAmount:
$ref: '#/components/schemas/amount'
allowancesTotalAmount:
$ref: '#/components/schemas/amount'
benefitsTotalAmount:
$ref: '#/components/schemas/amount'
bonusesTotalAmount:
$ref: '#/components/schemas/amount'
addOnsTotalAmount:
$ref: '#/components/schemas/amount'
taxesTotalAmount:
$ref: '#/components/schemas/amount'
trueUpsTotalAmount:
$ref: '#/components/schemas/amount'
oysterFeesTotalAmount:
$ref: '#/components/schemas/amount'
engagement:
type: object
properties:
name:
type: string
cutoffMonthDay:
type: integer
engagementType:
type: string
required:
- name
- cutoffMonthDay
- engagementType
required:
- engagementId
- currencyCode
- monthlyPaymentsTotalAmount
- allowancesTotalAmount
- benefitsTotalAmount
- bonusesTotalAmount
- addOnsTotalAmount
- taxesTotalAmount
- trueUpsTotalAmount
- oysterFeesTotalAmount
- engagement
payrolls:
type: array
items:
$ref: '#/components/schemas/payroll'
timeOffRequest:
type: object
properties:
timeOffRequestId:
type: string
engagement:
$ref: '#/components/schemas/timeOffEngagementDetails'
startDate:
type: string
format: date
endDate:
type: string
format: date
firstDayDuration:
type: string
pattern: ^[A-Z_]+$
lastDayDuration:
type: string
nullable: true
pattern: ^[A-Z_]+$
state:
type: string
pattern: ^[A-Z_]+$
type:
type: string
pattern: ^[A-Z_]+$
requesterComments:
type: string
nullable: true
rejectionReason:
type: string
nullable: true
reason:
type: string
pattern: ^[A-Z_]+$
periodInHours:
type: number
format: float
timeOffRequests:
type: array
items:
$ref: '#/components/schemas/timeOffRequest'
timeOffEntitlements:
type: array
items:
type: object
properties:
engagement:
$ref: '#/components/schemas/timeOffEngagementDetails'
annualEntitlement:
type: number
format: float
accrued:
type: number
format: float
carried:
type: number
format: float
adjustedAdhoc:
type: number
format: float
taken:
type: number
format: float
availableBalance:
type: number
format: float
upcoming:
type: number
format: float
projectedBalance:
type: number
format: float
units:
type: string
enum:
- DAYS
timeOffEngagementDetails:
type: object
properties:
engagementId:
type: string
name:
type: string
type:
type: string
pattern: ^[A-Z_]+$
countryCode:
type: string
meta:
type: object
properties:
items:
type: integer
count:
type: integer
page:
type: integer
pages:
type: integer
firstUrl:
type: string
lastUrl:
type: string
pageUrl:
type: string
nextUrl:
type: string
prevUrl:
type: string
asyncResponse:
type: object
properties:
meta:
type: object
properties:
operationKey:
type: string
error:
type: object
properties:
error:
type: object
properties:
message:
type: string
errors:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
fieldErrors:
type: object
properties:
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
operation:
type: object
properties:
request:
type: object
properties:
method:
type: string
path:
type: string
queryParams:
type: object
responseCode:
type: integer
data:
type: object
meta:
type: object
properties:
completed:
type: boolean
success:
type: boolean
AuthenticationCreateAccessTokenRequest:
type: object
properties:
client_id:
description: >-
The client_id of your Developer App. This can be found by visting
https://app.oysterhr.com/developer
type: string
example: 1234ABCD
client_secret:
description: The secret of your Developer App.
type: string
example: 1234ABCD
grant_type:
description: >-
First you need to request an `authorization_code`. Afterwards you
can request a `refresh_token`.
type: string
example: authorization_code
code:
description: The code is required when requesting an `authorization_code`.
type: string
example: 1234ABCD
redirect_uri:
description: >-
The redirect_uri is required when requesting an
`authorization_code`.
type: string
example: https://example.com/inbound
refresh_token:
description: >-
A `refresh_token` is required when requesting a `refresh_token`. A
`refresh_token` will be provided when requesting an
`authorization_code`
type: string
example: https://example.com/inbound
ExpensesDeclineExpenseRequest:
type: object
properties:
reason:
type: string
ExpensesCreateOperationKeyRequest:
type: object
properties:
description:
type: string
engagementId:
type: string
minLength: 1
name:
type: string
minLength: 1
incurredOn:
type: string
format: date
minLength: 1
category:
type: string
minLength: 1
receiptUrl:
type: string
minLength: 1
receiptAmount:
type: object
properties:
decimal:
type: string
minLength: 1
currencyCode:
type: string
minLength: 1
required:
- decimal
- currencyCode
required:
- engagementId
- name
- incurredOn
- category
- receiptUrl
- receiptAmount
TimeOffRejectRequestRequest:
type: object
properties:
reason:
type: string
required:
- reason
ExpensesGetByIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/expense'
required:
- data
CompanyDetailsRetrieveResponse:
type: object
properties:
data:
$ref: '#/components/schemas/company'
required:
- data
DepartmentsGetAllResponse:
type: object
properties:
data:
$ref: '#/components/schemas/departments'
meta:
$ref: '#/components/schemas/meta'
required:
- data
- meta
EngagementsGetByIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/engagement'
required:
- data
EngagementsGetAllResponse:
type: object
properties:
data:
$ref: '#/components/schemas/engagements'
meta:
$ref: '#/components/schemas/meta'
required:
- data
- meta
OperationsGetByOperationKeyResponse:
type: object
properties:
data:
$ref: '#/components/schemas/operation'
required:
- data
PayrollGetByIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/payroll'
required:
- data
PayrollGetAllPayrollsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/payrolls'
meta:
$ref: '#/components/schemas/meta'
required:
- data
- meta
TimeOffGetEntitlementsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/timeOffEntitlements'
meta:
$ref: '#/components/schemas/meta'
required:
- data
- meta
TimeOffGetRequestResponse:
type: object
properties:
data:
$ref: '#/components/schemas/timeOffRequest'
required:
- data
TimeOffGetAllRequestsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/timeOffRequests'
meta:
$ref: '#/components/schemas/meta'
required:
- data
- meta
securitySchemes:
bearer_auth:
type: http
scheme: bearer
x-readme:
explorer-enabled: true
proxy-enabled: true
_id: 6514040da1ecab004a312d3c