Oyster

App · 20 actions

Read employment, time off, expenses, invoices and payroll records.

Actions

ActionWhat it does
Get companyRetrieve company details.
Get contract changeRetrieve an individual contract change request.
Get engagementRetrieve an individual engagement.
Get expenseRetrieve an individual expense.
Get invoiceRetrieve an invoice.
Get time off requestRetrieve an individual request.
Get time sheetRetrieve an individual time sheet.
List allowancesRetrieve allowances for engagement.
List bonusesRetrieve bonuses for engagement.
List contract changesRetrieve all contract changes.
List departmentsRetrieve all departments.
List documentsRetrieve documents for engagement.
List engagementsRetrieve all engagements.
List expensesRetrieve all expenses.
List invoicesRetrieve all invoices.
List payslipsRetrieve payslips for engagement.
List public holidaysRetrieve public holidays.
List time off entitlementsRetrieve entitlements.
List time off requestsRetrieve all requests.
List time sheetsRetrieve 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

IdidtextRequired
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

IdidtextRequired
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

IdidtextRequired
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

IdentifieridentifiertextRequired
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

IdidtextRequired
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

IdidtextRequired
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

IdidtextRequired
Id.
Per pageper_pagenumber
Per page.
Pagepagenumber
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

IdidtextRequired
Id.
Per pageper_pagenumber
Per page.
Pagepagenumber
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 pageper_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 pageper_pagenumber
Per page.
Pagepagenumber
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

IdidtextRequired
Id.
Per pageper_pagenumber
Per page.
Pagepagenumber
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 pageper_pagenumber
Per page.
Pagepagenumber
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

Pagepagenumber
Page.
Per pageper_pagenumber
Per page.
Queryquerytext
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 pageper_pagenumber
Per page.
Reference codes[]reference_codes_list
Reference codes .
Payroll period frompayroll_period_fromdate
Payroll period from.
Payroll period topayroll_period_todate
Payroll period to.
Issue date fromissue_date_fromdate
Issue date from.
Issue date toissue_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

IdidtextRequired
Id.
Per pageper_pagenumber
Per page.
Pagepagenumber
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 codecountry_codetext
ISO 3166-1 alpha-2 country code
Subdivision codesubdivision_codetext
ISO 3166-2 subdivision code
Engagementengagement_idtext
Engagement id.
Start datestart_datedateRequired
Start date.
End dateend_datedateRequired
End date.
Per pageper_pagenumber
Per page.
Pagepagenumber
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 pageper_pagenumber
Per page.
Pagepagenumber
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 pageper_pagenumber
Per page.
Pagepagenumber
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 pageper_pagenumber
Per page.
Pagepagenumber
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"
    }
  }
}

On this page