Oyster
App · 20 actions
Read employment, time off, expenses, invoices and payroll records.
Actions
| Action | What it does |
|---|---|
| Get company | Retrieve company details. |
| Get contract change | Retrieve an individual contract change request. |
| Get engagement | Retrieve an individual engagement. |
| Get expense | Retrieve an individual expense. |
| Get invoice | Retrieve an invoice. |
| Get time off request | Retrieve an individual request. |
| Get time sheet | Retrieve an individual time sheet. |
| List allowances | Retrieve allowances for engagement. |
| List bonuses | Retrieve bonuses for engagement. |
| List contract changes | Retrieve all contract changes. |
| List departments | Retrieve all departments. |
| List documents | Retrieve documents for engagement. |
| List engagements | Retrieve all engagements. |
| List expenses | Retrieve all expenses. |
| List invoices | Retrieve all invoices. |
| List payslips | Retrieve payslips for engagement. |
| List public holidays | Retrieve public holidays. |
| List time off entitlements | Retrieve entitlements. |
| List time off requests | Retrieve all requests. |
| List time sheets | Retrieve all time sheets. |
Get company
Retrieve company details.
Inputs
None.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"addresses": {
"billingAddress": {
"addressId": "example",
"addressLine1": "example",
"addressLine2": "example",
"city": "example",
"countryCode": "example",
"postalCode": "example",
"region": "example"
},
"corporateAddress": {
"addressId": "example",
"addressLine1": "example",
"addressLine2": "example",
"city": "example",
"countryCode": "example",
"postalCode": "example",
"region": "example"
}
},
"companyId": "example",
"name": "example",
"registrationNumber": "example"
}
}
}Get contract change
Retrieve an individual contract change request.
Inputs
- Id
idtextRequired - Id.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"agreementAmendment": {
"contentType": "example",
"filename": "example",
"url": "example"
},
"applicableFrom": "2026-11-01",
"changes": {
"allowances": {
"added": [],
"removed": []
},
"bonuses": {
"added": [],
"removed": []
},
"compensation": {
"salary": {
"from": {
"currencyCode": "example",
"decimal": "example"
},
"to": {
"currencyCode": "example",
"decimal": "example"
}
},
"salaryAbsorbable": {
"from": false,
"to": false
}
},
"positionDetails": {
"jobDescription": {
"from": "example",
"to": "example"
},
"jobTitle": {
"from": "example",
"to": "example"
}
}
},
"changesRequested": [],
"createdAt": "2026-11-01T12:00:00Z",
"effectiveFrom": "2026-11-01",
"engagement": {
"countryCode": "example",
"id": "example",
"name": "example",
"type": "EMPLOYMENT"
},
"expirationDate": "2026-11-01",
"id": "example",
"oneOffBonusPayment": {
"currencyCode": "example",
"decimal": "example"
},
"oysterServiceAgreementAmendment": {
"contentType": "example",
"filename": "example",
"url": "example"
},
"requestedBy": {
"name": "example"
},
"state": "example",
"updatedAt": "2026-11-01T12:00:00Z"
}
}
}Get engagement
Retrieve an individual engagement.
Inputs
- Id
idtextRequired - Id.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"benefitEnrollments": [],
"contract": {
"billingType": "FIXED",
"contractId": "example",
"email": "example",
"id": "example",
"name": "example",
"taxIdNumber": "example",
"workEmail": "example"
},
"countryCode": "example",
"department": {
"departmentId": "example",
"description": "example",
"name": "example"
},
"employment": {
"email": "example",
"employmentId": "example",
"employmentType": "FULL-TIME",
"fullLegalName": "example",
"id": "example",
"lastDayOn": "2026-11-01",
"payrollTeamMember": false,
"salary": {
"currencyCode": "example",
"decimal": "example"
},
"type": "FULL-TIME",
"workEmail": "example"
},
"engagementId": "example",
"engagementType": "EMPLOYMENT",
"modifiedAt": "2026-11-01T12:00:00Z",
"personalDetails": {
"addresses": {
"livingAddress": {
"addressId": "example",
"addressLine1": "example",
"addressLine2": "example",
"city": "example",
"countryCode": "example",
"postalCode": "example",
"region": "example"
},
"mailingAddress": {
"addressId": "example",
"addressLine1": "example",
"addressLine2": "example",
"city": "example",
"countryCode": "example",
"postalCode": "example",
"region": "example"
}
},
"citizenships": [],
"dateOfBirth": "example",
"name": "example",
"phoneNumbers": {
"default": {
"countryCode": "example",
"number": "example"
},
"emergency": {
"countryCode": "example",
"number": "example"
}
}
},
"role": "example",
"startDate": "2026-11-01",
"state": "example",
"terminations": []
}
}
}Get expense
Retrieve an individual expense.
Inputs
- Id
idtextRequired - Id.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"amount": {
"currencyCode": "example",
"decimal": "example"
},
"category": "example",
"description": "example",
"engagement": {
"engagementId": "example",
"engagementType": "example",
"name": "example"
},
"expenseId": "example",
"incurredOn": "2026-11-01",
"name": "example",
"receiptAmount": {
"currencyCode": "example",
"decimal": "example"
},
"receiptUrl": "example",
"reviewState": "UNREVIEWED",
"reviewedAt": "2026-11-01T12:00:00Z",
"source": "example",
"submittedAt": "2026-11-01T12:00:00Z"
}
}
}Get invoice
Retrieve an invoice.
Inputs
- Identifier
identifiertextRequired - Identifier.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"amount": {
"currencyCode": "example",
"decimal": "example"
},
"appliedCredit": [],
"charge": {
"amount": {
"currencyCode": "example",
"decimal": "example"
},
"amountDue": {
"currencyCode": "example",
"decimal": "example"
},
"id": "example",
"status": "NO_PAYMENT"
},
"customer": {
"id": "example",
"name": "example"
},
"dueDate": "2026-11-01",
"files": {
"breakdown": {
"contentType": "example",
"title": "example",
"url": "example"
},
"document": {
"contentType": "example",
"title": "example",
"url": "example"
}
},
"id": "example",
"issueDate": "2026-11-01",
"lineItems": [],
"payout": {
"amount": {
"currencyCode": "example",
"decimal": "example"
},
"id": "example",
"status": "NOT_INITIATED"
},
"payrollMonth": "example",
"payrollYear": "example",
"referenceCode": "example",
"status": "example",
"taxAmount": {
"currencyCode": "example",
"decimal": "example"
},
"taxPercentage": "example",
"type": "PREFUNDING"
}
}
}Get time off request
Retrieve an individual request.
Inputs
- Id
idtextRequired - Id.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"approvedAt": "2026-11-01T12:00:00Z",
"attachment": {
"contentType": "example",
"filename": "example",
"url": "example"
},
"endDate": "2026-11-01",
"engagement": {
"countryCode": "example",
"engagementId": "example",
"name": "example",
"type": "example"
},
"firstDayDuration": "example",
"firstDayDurationInHours": 1.0,
"lastDayDuration": "example",
"lastDayDurationInHours": 1.0,
"periodInHours": 1.0,
"reason": "example",
"rejectedAt": "2026-11-01T12:00:00Z",
"rejectionReason": "example",
"requesterComments": "example",
"startDate": "2026-11-01",
"state": "example",
"submittedAt": "2026-11-01T12:00:00Z",
"timeOffRequestId": "example",
"type": "example"
}
}
}Get time sheet
Retrieve an individual time sheet.
Inputs
- Id
idtextRequired - Id.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": {
"amendmentTimeSheetId": "example",
"cadence": "MONTHLY",
"confirmedBy": "example",
"createdBy": "example",
"engagement": {
"countryCode": "example",
"engagementId": "example",
"name": "example",
"type": "example"
},
"entries": [],
"flexibleWorkArrangement": false,
"hasAmendmentTimeSheet": false,
"id": "example",
"isAmendment": false,
"locked": false,
"originalTimeSheetId": "example",
"status": "PENDING_SUBMISSION",
"statusReason": "example",
"submittedBy": "example",
"timeOffs": [],
"timePeriod": {
"endDate": "2026-11-01",
"month": "example",
"startDate": "2026-11-01",
"year": "example"
},
"totals": {
"notWorked": {
"hours": 1,
"minutes": 1
},
"timeOff": {
"hours": 1,
"minutes": 1
},
"worked": {
"hours": 1,
"minutes": 1
},
"workedOnHolidays": {
"hours": 1,
"minutes": 1
},
"workedOnWeekdays": {
"hours": 1,
"minutes": 1
},
"workedOnWeekends": {
"hours": 1,
"minutes": 1
}
},
"workSummary": []
}
}
}List allowances
Retrieve allowances for engagement.
Inputs
- Id
idtextRequired - Id.
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List bonuses
Retrieve bonuses for engagement.
Inputs
- Id
idtextRequired - Id.
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List contract changes
Retrieve all contract changes.
Inputs
- Per page
per_pagenumber - Per page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List departments
Retrieve all departments.
Inputs
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List documents
Retrieve documents for engagement.
Inputs
- Id
idtextRequired - Id.
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List engagements
Retrieve all engagements.
Inputs
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List expenses
Retrieve all expenses.
Inputs
- Page
pagenumber - Page.
- Per page
per_pagenumber - Per page.
- Query
querytext - Query.
- Review states[]
review_states_list - Review states .One or more of:
APPROVED,DECLINED,UNREVIEWED.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List invoices
Retrieve all invoices.
Inputs
- Per page
per_pagenumber - Per page.
- Reference codes[]
reference_codes_list - Reference codes .
- Payroll period from
payroll_period_fromdate - Payroll period from.
- Payroll period to
payroll_period_todate - Payroll period to.
- Issue date from
issue_date_fromdate - Issue date from.
- Issue date to
issue_date_todate - Issue date to.
- Types[]
types_list - Types .One or more of:
PREFUNDING,SETTLEMENT,MONTHLY_PAYMENT(Monthly payment),CLOSING,DEPOSIT,MANUAL,MANUAL_GLOBAL_PAYROLL(Manual global payroll),MANUAL_SALARY_INSIGHTS(Manual salary insights),SCALE,PLATFORM_PLAN(Platform plan), and 11 more. - Statuses[]
statuses_list - Statuses .One or more of:
DISPUTED,VOIDED,WAITING_APPROVAL(Waiting approval),READY_FOR_REVIEW(Ready for review),APPROVED,AUTO_APPROVED(Auto approved). - Engagement ids[]
engagement_ids_list - Engagement ids .
- Customer ids[]
customer_ids_list - Customer ids .
- Charge statuses[]
charge_statuses_list - Charge statuses .One or more of:
PENDING,DIRECT_DEBIT_IN_PROGRESS(Direct debit in progress),DIRECT_DEBIT_FAILED(Direct debit failed),CHARGED_BACK(Charged back),PAID,WAITING_FOR_WIRE_TRANSFER(Waiting for wire transfer),NO_PAYMENT(No payment),OVERDUE,PARTIALLY_PAID(Partially paid),VOIDED. - Payout statuses[]
payout_statuses_list - Payout statuses .One or more of:
NO_PAYMENT(No payment),NOT_INITIATED(Not initiated),INITIATED,IN_PROGRESS(In progress),PAID,RETURNED.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List payslips
Retrieve payslips for engagement.
Inputs
- Id
idtextRequired - Id.
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List public holidays
Retrieve public holidays.
Inputs
- Country code
country_codetext - ISO 3166-1 alpha-2 country code
- Subdivision code
subdivision_codetext - ISO 3166-2 subdivision code
- Engagement
engagement_idtext - Engagement id.
- Start date
start_datedateRequired - Start date.
- End date
end_datedateRequired - End date.
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List time off entitlements
Retrieve entitlements.
Inputs
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List time off requests
Retrieve all requests.
Inputs
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
- Engagement ids[]
engagement_ids_list - Engagement ids .
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}List time sheets
Retrieve all time sheets.
Inputs
- Per page
per_pagenumber - Per page.
- Page
pagenumber - Page.
Outputs
dataobject- Service response.
Example output
{
"data": {
"data": [],
"meta": {
"count": 1,
"deprecation": {
"at": "example",
"link": {
"rel": "example",
"url": "example"
},
"sunset": "example"
},
"firstUrl": "example",
"items": 1,
"lastUrl": "example",
"nextUrl": "example",
"page": 1,
"pageUrl": "example",
"pages": 1,
"prevUrl": "example"
}
}
}