--- openapi: 3.0.3 info: title: Affix API description: | The affixapi.com API documentation. # Introduction Affix API is an OAuth 2.1 application that allows developers to access customer data, without developers needing to manage or maintain integrations; or collect login credentials or API keys from users for these third party systems. # OAuth 2.1 Affix API follows the [OAuth 2.1 spec](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-08). As an OAuth application, Affix API handles not only both the collection of sensitive user credentials or API keys, but also builds and maintains the integrations with the providers, so you don't have to. # How to obtain an access token in order to get started, you must: - register a `client_id` - direct your user to the sign in flow (`https://connect.affixapi.com` [with the appropriate query parameters](https://github.com/affixapi/starter-kit/tree/master/connect)) - capture `authorization_code` we will send to your redirect URI after the sign in flow is complete and exchange that `authorization_code` for a Bearer token # Sandbox keys (xhr mode) ### dev ``` eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzODIzNTNlMi05N2ZiLTRmMWEtOTYxYy0zZDI5OTViNzYxMTUiLCJpYXQiOjE3MTE4MTA3MTQsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUuZGV2LmVuZ2luZWVyaW5nLmFmZml4YXBpLmNvbSIsInN1YiI6InhociIsImF1ZCI6IjNGREFFREY5LTFEQ0E0RjU0LTg3OTQ5RjZBLTQxMDI3NjQzIn0.zUJPaT6IxcIdr8b9iO6u-Rr5I-ohTHPYTrQGrgOFghbEbovItiwr9Wk479GnJVJc3WR8bxAwUMAE4Ul6Okdk6Q ``` #### `employees` endpoint sample: ``` curl --fail \ -X GET \ -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzODIzNTNlMi05N2ZiLTRmMWEtOTYxYy0zZDI5OTViNzYxMTUiLCJpYXQiOjE3MTE4MTA3MTQsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUuZGV2LmVuZ2luZWVyaW5nLmFmZml4YXBpLmNvbSIsInN1YiI6InhociIsImF1ZCI6IjNGREFFREY5LTFEQ0E0RjU0LTg3OTQ5RjZBLTQxMDI3NjQzIn0.zUJPaT6IxcIdr8b9iO6u-Rr5I-ohTHPYTrQGrgOFghbEbovItiwr9Wk479GnJVJc3WR8bxAwUMAE4Ul6Okdk6Q' \ 'https://dev.api.affixapi.com/2023-03-01/xhr/employees' ``` ### prod ``` eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzYjg4MDc2NC1kMGFmLTQ5ZDAtOGM5OS00YzIwYjE2MTJjOTMiLCJpYXQiOjE3MTE4MTA4NTgsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUucHJvZC5lbmdpbmVlcmluZy5hZmZpeGFwaS5jb20iLCJzdWIiOiJ4aHIiLCJhdWQiOiIwOEJCMDgxRS1EOUFCNEQxNC04REY5OTIzMy02NjYxNUNFOSJ9.n3pJmmfegU21Tko_TyUyCHi4ITvfd75T8NFFTHmf1r8AI8yCUYTWdfNjyZZWcZD6z50I3Wsk2rAd8GDWXn4vlg ``` #### `employees` endpoint sample: ``` curl --fail \ -X GET \ -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzYjg4MDc2NC1kMGFmLTQ5ZDAtOGM5OS00YzIwYjE2MTJjOTMiLCJpYXQiOjE3MTE4MTA4NTgsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUucHJvZC5lbmdpbmVlcmluZy5hZmZpeGFwaS5jb20iLCJzdWIiOiJ4aHIiLCJhdWQiOiIwOEJCMDgxRS1EOUFCNEQxNC04REY5OTIzMy02NjYxNUNFOSJ9.n3pJmmfegU21Tko_TyUyCHi4ITvfd75T8NFFTHmf1r8AI8yCUYTWdfNjyZZWcZD6z50I3Wsk2rAd8GDWXn4vlg' \ 'https://api.affixapi.com/2023-03-01/xhr/employees' ``` # Compression We support `brotli`, `gzip`, and `deflate` compression algorithms. To enable, pass the `Accept-Encoding` header with one or all of the values: `br`, `gzip`, `deflate`, or `identity` (no compression) In the response, you will receive the `Content-Encoding` response header indicating the compression algorithm used in the data payload to enable you to decompress the result. If the `Accept-Encoding: identity` header was passed, no `Content-Encoding` response header is sent back, as no compression algorithm was used. # Webhooks An exciting feature for HR/Payroll modes are webhooks. If enabled, your `webhook_uri` is set on your `client_id` for the respective environment: `dev | prod` Webhooks are configured to make live requests to the underlying integration 1x/hr, and if a difference is detected since the last request, we will send a request to your `webhook_uri` with this shape: ``` { added: [ { ..., date_of_birth: '2010-08-06', display_full_name: 'Daija Rogahn', employee_number: '57993', employment_status: 'pending', employment_type: 'other', employments: [ { currency: 'eur', effective_date: '2022-02-25', employment_type: 'other', job_title: 'Dynamic Implementation Manager', pay_frequency: 'semimonthly', pay_period: 'YEAR', pay_rate: 96000, }, ], first_name: 'Daija', ... } ], removed: [], updated: [ { ..., date_of_birth: '2009-11-09', display_full_name: 'Lourdes Stiedemann', employee_number: '63189', employment_status: 'leave', employment_type: 'full_time', employments: [ { currency: 'gbp', effective_date: '2023-01-16', employment_type: 'full_time', job_title: 'Forward Brand Planner', pay_frequency: 'semimonthly', pay_period: 'YEAR', pay_rate: 86000, }, ], first_name: 'Lourdes', } ] } ``` the following headers will be sent with webhook requests: ``` x-affix-api-signature: ab8474e609db95d5df3adc39ea3add7a7544bd215c5c520a30a650ae93a2fba7 x-affix-api-origin: webhooks-employees-webhook user-agent: affixapi.com ``` Before trusting the payload, you should sign the payload and verify the signature matches the signature sent by the `affixapi.com` service. This secures that the data sent to your `webhook_uri` is from the `affixapi.com` server. The signature is created by combining the signing secret (your `client_secret`) with the body of the request sent using a standard HMAC-SHA256 keyed hash. The signature can be created via: - create an `HMAC` with your `client_secret` - update the `HMAC` with the payload - get the hex digest -> this is the signature Sample `typescript` code that follows this recipe: ``` import { createHmac } from 'crypto'; export const computeSignature = ({ str, signingSecret, }: { signingSecret: string; str: string; }): string => { const hmac = createHmac('sha256', signingSecret); hmac.update(str); const signature = hmac.digest('hex'); return signature; }; ``` While verifying the Affix API signature header should be your primary method of confirming validity, you can also whitelist our outbound webhook static IP addresses. ``` dev: - 52.210.169.82 - 52.210.38.77 - 3.248.135.204 prod: - 52.51.160.102 - 54.220.83.244 - 3.254.213.171 ``` ## Rate limits Open endpoints (not gated by an API key) (applied at endpoint level): - 15 requests every 1 minute (by IP address) - 25 requests every 5 minutes (by IP address) Gated endpoints (require an API key) (applied at endpoint level): - 40 requests every 1 minute (by IP address) - 40 requests every 5 minutes (by `client_id`) Things to keep in mind: - Open endpoints (not gated by an API key) will likely be called by your users, not you, so rate limits generally would not apply to you. - As a developer, rate limits are applied at the endpoint granularity. - For example, say the rate limits below are 10 requests per minute by ip. from that same ip, within 1 minute, you get: - 10 requests per minute on `/orders`, - another 10 requests per minute on `/items`, - and another 10 requests per minute on `/identity`, - for a total of 30 requests per minute. contact: email: developers@affixapi.com termsOfService: https://affixapi.com/terms-and-conditions x-logo: uri: https://media.licdn.com/dms/image/D4E0BAQG0eRUQzmxDjQ/company-logo_100_100/0/1680762091788?e=1698883200&v=beta&t=ITsfWc2YmsMBFBtNdSNMB0kdBTKt-eGHjYeWhxDM6qg altText: Affix API logo version: '2023-03-01' servers: - url: https://api.affixapi.com description: Production server (EU) - url: https://dev.api.affixapi.com description: Development server (EU) tags: - name: Core description: | Operations related to obtaining core information about the Affix API platform - name: Management description: | Operations related to obtaining, getting information on, or disconnecting, an access token - name: XHR (Vertically-integrated) description: | Operations related to retrieving end customer data from a customer's credentials login, for data migrations, or continuous integrations. paths: "/providers": get: x-public: true x-amazon-apigateway-integration: type: mock operationId: providers summary: Providers description: 'Retrieve the api modes (official, xhr) and providers for the respective modes ' tags: - Core responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/ProvidersResponse" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/management/client": get: security: - basic: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: client summary: Client description: 'View client attributes ' tags: - Management responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/ClientResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" post: security: - basic: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: updateClient summary: Update client description: | Update attributes of the client. Update the `name`, `client_secret`, or `webhook_uri` of the client tags: - Management requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/ClientRequest" responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/ClientResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/AuthenticationError" '409': "$ref": "#/components/responses/Conflict" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/management/tokens": get: security: - basic: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: tokens summary: Tokens description: 'View tokens and token status for respective client ' tags: - Management responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/TokensResponse" '400': "$ref": "#/components/responses/BadRequest" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/management/token": post: x-public: true x-amazon-apigateway-integration: type: mock operationId: token summary: Create token description: 'Exchange an `authorization_code` for an `access_token` after receiving on from the `redirect_uri` you specifiy after a successful user connection ' tags: - Management requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/TokenRequest" responses: '201': description: Success content: application/json: schema: "$ref": "#/components/schemas/TokenResponse" '400': "$ref": "#/components/responses/BadRequest" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/management/introspect": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: introspect summary: Inspect token description: 'Retrieve data about the token, such as `scopes`, `mode`, `provider`, and if it is active ' tags: - Management responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/IntrospectResponse" '400': "$ref": "#/components/responses/BadRequest" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/management/disconnect": post: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: disconnect summary: Disconnect token description: 'Disconnect the token. A disconnected token will no longer return data. Data requests with a disconnected token will return a 403 Forbidden ' tags: - Management responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/DisconnectResponse" '403': "$ref": "#/components/responses/Forbidden" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/xhr/company": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrCompanies20230301 summary: Company description: 'Retrieve company information ' tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Companies20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/employees": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrEmployees20230301 summary: Employees description: | List the individuals (employees, contractors, accountants, and others) listed in the HRIS/Payroll software tags: - XHR (Vertically-integrated) - '2023-03-01' parameters: - in: query name: employment_status required: false schema: "$ref": "#/components/schemas/EmploymentStatusNotNullNotNullable" description: | Optional query parameter. Use to enable server-side filtering of the `employment_status` attribute. Will only include individuals with that attribute explicitly set (ie if an individuals has a `null`, it will not be returned if this parameter is set) responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Employees20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/groups": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrGroups20230301 summary: Groups description: | The Group object is used to represent any subset of employees, such as PayGroup, Team, or Department. Employees can be in multiple Groups. tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Groups20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/identity": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrIdentity20230301 summary: Identity description: 'List information of the user for the respective account ' tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/IdentityResponse" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" "/2023-03-01/xhr/payruns": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrPayruns20230301 summary: Payruns description: | List all the pay runs that occurred during the respective period. Supported integrations: - brain payroll - brightpay connect - deel - gusto - justworks - moorepay - onpay - oyster - parolla.ie - paycircle - payfit - pento.io - quickbooks online - remote.com - sageone - shape payroll - simplepay.ie - staffology - xero uk tags: - XHR (Vertically-integrated) - '2023-03-01' parameters: - in: query name: start_date required: true schema: "$ref": "#/components/schemas/StartDate" description: The start date of the search period - in: query name: end_date required: true schema: "$ref": "#/components/schemas/EndDate" description: The end date of the search period responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Payruns20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/payruns/{payrun_id}": parameters: - name: payrun_id in: path required: true description: The id of the payrun. schema: "$ref": "#/components/schemas/string" get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrPayslips20230301 summary: Payslips description: | Retrieves payslips from a specific payrun. Supported integrations: - brain payroll - brightpay connect - deel - gusto - justworks - moorepay - onpay - oyster - parolla.ie - paycircle - payfit - pento.io - quickbooks online - remote.com - sageone - shape payroll - simplepay.ie - staffology - xero uk tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Payslips20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/timesheets": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrTimesheets20230301 summary: Timesheets description: 'Retrieve Timesheets ' tags: - XHR (Vertically-integrated) - '2023-03-01' parameters: - in: query name: start_date required: true schema: "$ref": "#/components/schemas/StartDate" description: The start date of the search period - in: query name: end_date required: true schema: "$ref": "#/components/schemas/EndDate" description: The end date of the search period responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/Timesheets20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/time-off-entries": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrTimeOffEntries20230301 summary: Time off entries description: 'Retrieve time off / absence entries ' tags: - XHR (Vertically-integrated) - '2023-03-01' parameters: - in: query name: start_date required: true schema: "$ref": "#/components/schemas/StartDate" description: The start date of the search period - in: query name: end_date required: true schema: "$ref": "#/components/schemas/EndDate" description: The end date of the search period responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/TimeOffEntries20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/time-off-balances": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrTimeOffBalances20230301 summary: Time off balances description: 'Retrieve all time off balances. ' tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/TimeOffBalances20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" "/2023-03-01/xhr/work-locations": get: security: - access-token: [] x-public: true x-amazon-apigateway-integration: type: mock operationId: xhrWorkLocations20230301 summary: Work locations description: | The Location object is used to represent an address that can be associated with an employee tags: - XHR (Vertically-integrated) - '2023-03-01' responses: '200': description: Success content: application/json: schema: "$ref": "#/components/schemas/WorkLocations20230301Response" '202': "$ref": "#/components/responses/Accepted" '401': "$ref": "#/components/responses/AuthenticationError" '429': "$ref": "#/components/responses/TooManyRequests" '500': "$ref": "#/components/responses/InternalServerError" '501': "$ref": "#/components/responses/NotImplemented" components: securitySchemes: access-token: type: apiKey name: Authorization in: header description: | Token HTTP authentication. Allowed headers-- Authorization: Bearer ```shell Authorization: Bearer {TOKEN} ``` basic: type: apiKey name: Authorization in: header description: | Basic HTTP authentication. Base64 of `client_id:client_secret`. Since there can be many `client_secret` values, any current `client_secret` sufficies Allowed headers-- Authorization: Basic ```shell Authorization: Basic ZGVtbzpwQDU1dzByZA== ``` responses: BadRequest: description: Bad Request content: application/json: schema: type: object properties: message: type: string validation_error: type: string TooManyRequests: description: Rate Limited / Too Many Requests headers: Retry-After: schema: type: integer description: Retry your call after the specified amount of seconds content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" InternalServerError: description: Server Error content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" ServiceUnavailable: description: Service Unavailable (retry your request after a short period) headers: Retry-After: schema: type: integer description: Retry your call after the specified amount of seconds content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" AuthenticationError: description: Authentication Error content: application/json: schema: type: object required: - code - error - message properties: error: type: string description: The type of error enum: - authentication_error message: type: string description: 'A descriptive description of the error ' example: Your password is incorrect code: type: string enum: - incorrect_username_or_password - incorrect_mfa_or_otp - reauthentication_required // cookies are now expired - additional_account_setup_required // password reset, etc - captcha_challenge // amazon type1 captcha challenge (currently unsovable) - no_valid_accounts // not used currently but reserved for future use - insufficient_permission // not enough privileges (ie not an admin, or not enough provider scopes on a provider api token for the Affix scopes requested) Conflict: description: Not Found content: application/json: schema: type: object required: - error properties: code: type: string description: 'The authorization code insert that caused a conflict ' token: type: string description: 'The access token insert that caused a conflict ' error: type: string enum: - conflict description: 'The description of the type of error, ie conflict of two requests of the the same authorization code ' NotImplemented: description: Not Implemented content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" NotFound: description: Not Found content: application/json: schema: "$ref": "#/components/schemas/IdAndMessageResponse" Forbidden: description: Forbidden content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" Accepted: description: Accepted + pending (async job started) headers: Retry-After: schema: type: integer description: Retry your call after the specified amount of seconds content: application/json: schema: "$ref": "#/components/schemas/MessageResponse" schemas: EmploymentStatusNotNullNotNullable: type: string example: active enum: - active - inactive - pending - leave StartDate: type: string format: date example: '2021-01-01' EndDate: type: string format: date example: '2021-12-31' string: type: string ScopesRequest: type: string enum: - "/2023-03-01/official/company" - "/2023-03-01/official/employee" - "/2023-03-01/official/employees" - "/2023-03-01/official/groups" - "/2023-03-01/official/identity" - "/2023-03-01/official/time-off-balances" - "/2023-03-01/official/time-off-entries" - "/2023-03-01/official/timesheets" - "/2023-03-01/official/work-locations" - "/2023-03-01/xhr/company" - "/2023-03-01/xhr/employee" - "/2023-03-01/xhr/employees" - "/2023-03-01/xhr/groups" - "/2023-03-01/xhr/identity" - "/2023-03-01/xhr/payruns" - "/2023-03-01/xhr/payruns/:payrun_id" - "/2023-03-01/xhr/time-off-balances" - "/2023-03-01/xhr/time-off-entries" - "/2023-03-01/xhr/timesheets" - "/2023-03-01/xhr/work-locations" ModeRequest: type: string enum: - official - xhr MessageResponse: type: object required: - message properties: message: type: string ProviderRequest: type: string enum: - sandbox - bamboohr - breathe - cezanne - charliehr - deel - deputy - hailyhr - hibob - humaans - iris cascade - moorepay - nmbrs - parolla.ie - payfit - personio.de - planday - sagehr - saplinghr - staffology - xero uk - brain payroll - brightpay connect - buk - employment hero - epe - factorialhr - fourthhr - greythr - gusto - itrent - justworks - keypay - kontek.se - onpay - oysterhr - paycircle - pento.io - peoplehr - quickbooks online - remote.com - runa - sageone - shape payroll - simplepay.ie - sunfish - talenox - talentoz - unity - zenergy - zoho - zucchetti ModeResponse: type: string enum: - official - xhr ProviderResponse: type: string enum: - sandbox - bamboohr - breathe - cezanne - charliehr - deel - deputy - hailyhr - hibob - humaans - iris cascade - moorepay - nmbrs - parolla.ie - payfit - personio.de - planday - sagehr - saplinghr - staffology - xero uk - brain payroll - brightpay connect - buk - employment hero - epe - factorialhr - fourthhr - greythr - gusto - itrent - justworks - keypay - kontek.se - onpay - oysterhr - paycircle - pento.io - peoplehr - quickbooks online - remote.com - runa - sageone - shape payroll - simplepay.ie - sunfish - talenox - talentoz - unity - zenergy - zoho - zucchetti ProvidersResponse: type: array example: - mode: official providers: - bamboohr - breathe - cezanne - charliehr - deel - deputy - employment hero - factorialhr - hailyhr - hibob - humaans - iris cascade - moorepay - oysterhr - parolla.ie - payfit - peoplehr - personio.de - planday - remote.com - sagehr - saplinghr - simplepay.ie - staffology - xero uk - mode: xhr providers: - bamboohr - brightpay connect - buk - deel - deputy - employment hero - epe - factorialhr - fourthhr - greythr - gusto - hibob - itrent - justworks - keypay - kontek.se - moorepay - nmbrs - onpay - oysterhr - parolla.ie - pento.io - peoplehr - personio.de - quickbooks online - remote.com - runa - sageone - shape payroll - simplepay.ie - sunfish - talenox - talentoz - unity - xero uk - zenergy - zoho - zucchetti items: type: object required: - mode - providers properties: mode: type: string example: xhr "$ref": "#/components/schemas/ModeResponse" providers: type: array items: "$ref": "#/components/schemas/ProviderResponse" ClientResponse: type: object required: - client_id - client_secret - name - redirect_uris properties: client_id: readOnly: true description: The client ID you received when you first created the application example: 00000000-00000000-00000000-00000000 type: string client_secret: description: | The client secret(s). It is an array datatype to allow for rotation of secrets without downtime for your customers example: - ffffffff-ffffffff-ffffffff-ffffffff - aaaaaaaa-aaaaaaaa-aaaaaaaa-aaaaaaaa type: array items: type: string redirect_uris: description: | Indicates the URI to return the user to after authorization is complete, which is the endpoint on your server to receive the authorization_code. Must be identical to the redirect URI provided in the original link. Please email me after signup and I will set both your client secret and redirect_uri (required) when you reach out. example: - https://app.your-company.com - https://dev.app.your-company.com type: array items: type: string name: description: 'Name of your app that shows up in the Affix Connect application ' type: string example: Your App webhook_uri: description: 'If enabled, webhooks will be sent to this endpoint ' type: string example: https://webhooks.your-company.com/aaaaaaaa-aaaaaaaa-aaaaaaaa-aaaaaaaa nullable: true ClientRequest: type: object required: - client_secret - name - redirect_uris properties: client_secret: description: | The client secret(s). It is an array datatype to allow for rotation of secrets without downtime for your customers example: - ffffffff-ffffffff-ffffffff-ffffffff - aaaaaaaa-aaaaaaaa-aaaaaaaa-aaaaaaaa type: array items: type: string redirect_uris: description: | Indicates the URI to return the user to after authorization is complete, which is the endpoint on your server to receive the authorization_code. Must be identical to the redirect URI provided in the original link. Please email me after signup and I will set both your client secret and redirect_uri (required) when you reach out. example: - https://app.your-company.com - https://dev.app.your-company.com type: array items: type: string name: description: 'Name of your app that shows up in the Affix Connect application ' type: string example: Your App webhook_uri: description: 'If enabled, webhooks will be sent to this endpoint ' type: string example: https://webhooks.your-company.com/aaaaaaaa-aaaaaaaa-aaaaaaaa-aaaaaaaa nullable: true ScopesResponse: type: string enum: - "/2023-03-01/official/company" - "/2023-03-01/official/employee" - "/2023-03-01/official/employees" - "/2023-03-01/official/groups" - "/2023-03-01/official/identity" - "/2023-03-01/official/time-off-balances" - "/2023-03-01/official/time-off-entries" - "/2023-03-01/official/timesheets" - "/2023-03-01/official/work-locations" - "/2023-03-01/xhr/company" - "/2023-03-01/xhr/employee" - "/2023-03-01/xhr/employees" - "/2023-03-01/xhr/groups" - "/2023-03-01/xhr/identity" - "/2023-03-01/xhr/payruns" - "/2023-03-01/xhr/payruns/:payrun_id" - "/2023-03-01/xhr/time-off-balances" - "/2023-03-01/xhr/time-off-entries" - "/2023-03-01/xhr/timesheets" - "/2023-03-01/xhr/work-locations" TokensResponse: type: array items: type: object required: - token - scopes - mode - provider - valid properties: token: description: The client ID you received when you first created the application example: 00000000-00000000-00000000-00000000 type: string scopes: readOnly: true description: | One or more scope values indicating which parts of the user's account you wish to access. Note, slight deviation from the OAuth 2.1 spec in that the param is scopes (plural) is used vs scope (singular) example: - "/2023-03-01/payroll/employees" - "/2023-03-01/payroll/identity" - "/2023-03-01/payroll/payruns" - "/2023-03-01/payroll/payruns/:payrun_id" type: array items: type: string "$ref": "#/components/schemas/ScopesResponse" created_at: description: 'When the token was created (`/token` invocation) ' type: string format: date-time example: '2023-08-09T08:09:40.724Z' mode: description: The Affix API integration mode example: payroll "$ref": "#/components/schemas/ModeResponse" provider: description: The provider of the user's account you wish to access example: oysterhr "$ref": "#/components/schemas/ProviderResponse" valid: description: if the token is valid or not example: true type: boolean IdAndMessageResponse: type: object required: - message - id properties: message: type: string description: A description of the error id: type: string description: The id of the entity that the id applies. For example, the transaction id TokenRequest: type: object required: - client_id - client_secret - grant_type - redirect_uri - code properties: client_id: writeOnly: true description: The client ID you received when you first created the application example: 00000000-00000000-00000000-00000000 type: string client_secret: writeOnly: true description: | The client secret. Since there can be multiple `client_secret`s (to allow for rotation of secrets without downtime to your customers), any current `client_secret` is valid Please email me after signup and I will set both your client secret and redirect_uri (required) when you reach out. example: ffffffff-ffffffff-ffffffff-ffffffff type: string grant_type: writeOnly: true description: This is a hardcoded value required by the OAuth 2.1 spec example: authorization_code type: string enum: - authorization_code code: writeOnly: true description: This is the code you received in the query string example: Y2xpZW50IzkzMTU4MGQwLWYwYjctNGJiOC1iYmZmLWI4MTNlYzMxNTVjYXxjb2RlIzE1MmIwYjk3LTg2ZWMtNDZlNC1hZDUyLWY5ZTAxNzE2MDIwNAo= type: string redirect_uri: writeOnly: true description: | Indicates the URI to return the user to after authorization is complete, which is the endpoint on your server to receive the authorization_code. Must be identical to the redirect URI provided in the original link. Please email me after signup and I will set both your client secret and redirect_uri (required) when you reach out. example: https://example.com type: string TokenResponse: type: object required: - access_token - scopes - token_type - mode - provider properties: access_token: readOnly: true description: The issued access_token example: Y2xpZW50IzkzMTU4MGQwLWYwYjctNGJiOC1iYmZmLWI4MTNlYzMxNTVjYXx0b2tlbiM4ZDY5NzMwZi1kNzI1LTQ1ZjYtYTVlOC1mZmQ0NWE3ZjhkNDE= type: string mode: readOnly: true description: The Affix API integration mode example: payroll "$ref": "#/components/schemas/ModeResponse" provider: readOnly: true description: The provider of the user's account you wish to access example: oysterhr "$ref": "#/components/schemas/ProviderResponse" scopes: readOnly: true description: | One or more scope values indicating which parts of the user's account you wish to access. Note, slight deviation from the OAuth 2.1 spec in that the param is scopes (plural) is used vs scope (singular) example: - identity - census type: array items: type: string "$ref": "#/components/schemas/ScopesResponse" token_type: readOnly: true description: The token type to pass in the `Authorization` header example: Bearer type: string enum: - Bearer IntrospectResponse: type: object required: - client_id - provider - mode - scopes properties: client_id: readOnly: true description: The client ID you received when you first created the application example: 00000000-00000000-00000000-00000000 type: string mode: readOnly: true description: The Affix API integration mode example: payroll-employer "$ref": "#/components/schemas/ModeResponse" provider: readOnly: true description: The provider of the user's account you wish to access example: oysterhr "$ref": "#/components/schemas/ProviderResponse" scopes: readOnly: true description: | One or more scope values indicating which parts of the user's account you wish to access. Note, slight deviation from the OAuth 2.1 spec in that the param is scopes (plural) is used vs scope (singular) example: - identity - census type: array items: "$ref": "#/components/schemas/ScopesResponse" DisconnectResponse: type: object required: - disconnected properties: disconnected: readOnly: true description: The access token has been disconnected and is no longer allowed to be used by your application example: true type: boolean enum: - true addressResponse: type: object nullable: true required: - street_address - locality - administrative_area - country - post_code properties: street_address: example: 221 S Main Street nullable: true type: string locality: example: Yuma nullable: true type: string administrative_area: example: AZ description: | The administrative area of the address. If US or CA, the two-letter state or province abbreviation. Else, the province / administrative area; such as, `Dublin 2` or `County Cork` nullable: true type: string country: description: | The ISO-3166-2 two-letter abbreviation of the country. Reference https://en.wikipedia.org/wiki/ISO_3166-2 for more details example: IE nullable: true type: string enum: - - BZ - CA - CR - GT - MX - PA - SV - US - AR - BR - CL - CO - PE - AT - BE - CH - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GR - IE - IM - IS - IT - LI - LT - LU - LV - MK - NL - 'NO' - PL - PT - RO - RU - SE - SK - BD - CN - HK - ID - IL - IN - JP - KR - KZ - MO - MY - PH - PK - PS - SA - SG - TH - TJ - TM - TR - TW - VN - ZA - AU - NZ post_code: example: '30691' nullable: true type: string CompanyResponse: type: object required: - id - remote_id - legal_name - display_name - tax_id - address properties: id: description: The Affix-assigned id of the abscence example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true remote_id: description: the remote system-assigned id of the abscence example: '19202938' type: string nullable: true legal_name: type: string nullable: true example: Affix display_name: type: string nullable: true example: Affix API Limited tax_id: type: string nullable: true example: 12-3456789 address: "$ref": "#/components/schemas/addressResponse" Companies20230301Response: type: array items: "$ref": "#/components/schemas/CompanyResponse" employment-status-not-nullRequest: type: string nullable: true example: active enum: - active - inactive - pending - leave address-no-non-nullRequest: type: object nullable: true required: - street_address - locality - administrative_area - country - post_code properties: street_address: example: 221 S Main Street nullable: true type: string locality: example: Yuma nullable: true type: string administrative_area: example: AZ description: | The administrative area of the address. If US or CA, the two-letter state or province abbreviation. Else, the province / administrative area; such as, `Dublin 2` or `County Cork` nullable: true type: string country: description: | The ISO-3166-2 two-letter abbreviation of the country. Reference https://en.wikipedia.org/wiki/ISO_3166-2 for more details example: IE nullable: true type: string enum: - BZ - CA - CR - GT - MX - PA - SV - US - AR - BR - CL - CO - PE - AT - BE - CH - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GR - IE - IM - IS - IT - LI - LT - LU - LV - MK - NL - 'NO' - PL - PT - RO - RU - SE - SK - BD - CN - HK - ID - IL - IN - JP - KR - KZ - MO - MY - PH - PK - PS - SA - SG - TH - TJ - TM - TR - TW - VN - ZA - AU - NZ post_code: example: '30691' nullable: true type: string location-no-non-nullRequest: type: object nullable: true required: - id - remote_id - type - name - address properties: id: description: The Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string nullable: true name: description: System assigned description of the location example: NYC Office type: string nullable: true type: example: office description: | The location's type. In cases where there is no clear mapping, the original value passed through will be returned. type: string nullable: true address: "$ref": "#/components/schemas/address-no-non-nullRequest" employment-history-no-non-nullRequest: type: object required: - job_title - effective_date - group_id - group_remote_id - group_name - manager_id - manager_remote_id properties: job_title: example: Software Developer type: string effective_date: example: '2020-10-11' type: string format: date group_id: example: 4B9bKBpX5tnwjiG93TAqF7ci nullable: true type: string group_remote_id: example: '49' nullable: true type: string group_name: example: Engineering nullable: true type: string manager_id: type: string nullable: true manager_remote_id: type: string nullable: true currency-not-nullRequest: type: string example: eur nullable: true enum: - usd - gbp - eur - sek - cad compensation-history-no-non-nullRequest: type: object required: - pay_rate - pay_period - pay_frequency - employment_type - currency - effective_date - notes properties: pay_rate: example: 85000 type: number pay_period: example: year type: string pay_frequency: example: semimonthly type: string enum: - year - weekly - biweekly - semimonthly - monthly - other employment_type: example: full_time type: string enum: - full_time - part_time - contractor - other currency: example: eur "$ref": "#/components/schemas/currency-not-nullRequest" effective_date: example: '2020-10-11' type: string format: date notes: example: Salary Adjustment type: string group-no-null-enumRequest: type: object example: id: 4B9bKBpX5tnwjiG93TAqF7ci remote_id: df6c28e8 name: backend type: team required: - id - remote_id - name - type properties: id: example: 4B9bKBpX5tnwjiG93TAqF7ci nullable: true type: string remote_id: example: '49' nullable: true type: string name: example: Customer Success nullable: true type: string type: example: TEAM nullable: true type: string enum: - department - team - cost_centre - pay_group groups-no-null-enumRequest: type: array nullable: true example: - id: 4B9bKBpX5tnwjiG93TAqF7ci remote_id: df6c28e8 name: backend type: team - id: 132Xpnw2a38aaQG93TAqF7ci remote_id: 355c65922637 name: engineering type: department items: "$ref": "#/components/schemas/group-no-null-enumRequest" CreateEmployeeRequest: type: object required: - first_name - last_name properties: employee_number: nullable: true example: '2' type: string first_name: description: the first name of the individual example: Greg type: string last_name: description: the last name of the individual example: Hirsch type: string display_full_name: example: Hirsch nullable: true type: string nationality: example: Irish nullable: true type: string job_title: example: Software developer nullable: true type: string work_email: description: the work email of the individual example: greg@affixapi.com nullable: true type: string personal_email: description: the personal email of the individual example: greg@gmail.com nullable: true type: string mobile_phone_number: description: "+1234567890" example: Hirsch nullable: true type: string tax_id: example: '1234567890' nullable: true type: string gender: example: male nullable: true type: string enum: - male - female - not_specified ethnicity: nullable: true example: white type: string enum: - asian - black - hispanic - mixed - not_specified - other - white marital_status: nullable: true example: single type: string description: | `other` option can include co-habitating, civil partnership, separated, widowed, etc enum: - single - married - divorced - not_specified - other date_of_birth: example: '1990-11-10' nullable: true type: string format: date employment_status: "$ref": "#/components/schemas/employment-status-not-nullRequest" employment_type: nullable: true example: full_time type: string enum: - full_time - part_time - contractor - other start_date: example: '2020-10-11' nullable: true type: string format: date termination_date: example: '2021-10-12' nullable: true type: string format: date avatar: example: http://alturl.com/h2h8m nullable: true type: string home_location: "$ref": "#/components/schemas/address-no-non-nullRequest" work_location: "$ref": "#/components/schemas/location-no-non-nullRequest" manager: nullable: true type: object required: - first_name - last_name - id - work_email - remote_id properties: first_name: nullable: true type: string last_name: nullable: true type: string id: type: string work_email: nullable: true type: string remote_id: nullable: true type: string bank_account: nullable: true type: object required: - account_number - bank_name - bic - holder_name - iban properties: account_number: nullable: true type: string bank_name: nullable: true type: string bic: nullable: true type: string holder_name: nullable: true type: string iban: nullable: true type: string employment_history: nullable: true type: array items: "$ref": "#/components/schemas/employment-history-no-non-nullRequest" compensation_history: nullable: true type: array items: "$ref": "#/components/schemas/compensation-history-no-non-nullRequest" custom_fields: nullable: true type: object example: t_shirt_size: medium groups: "$ref": "#/components/schemas/groups-no-null-enumRequest" dependents: nullable: true type: array items: type: object required: - name - relationship properties: name: nullable: true type: string relationship: nullable: true type: string emergency_contacts: nullable: true type: array items: type: object required: - first_name - last_name - relationship - mobile_phone_number - primary_contact properties: first_name: nullable: true type: string last_name: nullable: true type: string relationship: nullable: true type: string mobile_phone_number: nullable: true type: string primary_contact: nullable: true type: boolean employment-statusResponse: type: string nullable: true example: active enum: - - active - inactive - pending - leave locationResponse: type: object nullable: true required: - id - remote_id - type - name - address properties: id: description: The Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string nullable: true name: description: System assigned description of the location example: NYC Office type: string nullable: true type: example: office description: | The location's type. In cases where there is no clear mapping, the original value passed through will be returned. type: string nullable: true address: "$ref": "#/components/schemas/addressResponse" employment-historyResponse: type: object required: - job_title - effective_date - group_id - group_remote_id - group_name - manager_id - manager_remote_id properties: job_title: example: Software Developer nullable: true type: string effective_date: example: '2020-10-11' nullable: true type: string format: date group_id: example: 4B9bKBpX5tnwjiG93TAqF7ci nullable: true type: string group_remote_id: example: '49' nullable: true type: string group_name: example: Engineering nullable: true type: string manager_id: type: string nullable: true manager_remote_id: type: string nullable: true CurrencyResponse: type: string example: eur nullable: true enum: - - usd - gbp - eur - sek - cad compensation-historyResponse: type: object required: - pay_rate - pay_period - pay_frequency - employment_type - currency - effective_date - notes properties: pay_rate: example: 85000 nullable: true type: number pay_period: example: year nullable: true type: string pay_frequency: example: semimonthly nullable: true type: string enum: - year - weekly - biweekly - semimonthly - monthly - other - employment_type: example: full_time nullable: true type: string enum: - full_time - part_time - contractor - other - currency: example: eur "$ref": "#/components/schemas/CurrencyResponse" effective_date: example: '2020-10-11' nullable: true type: string format: date notes: example: Salary Adjustment nullable: true type: string groupResponse: type: object example: id: 4B9bKBpX5tnwjiG93TAqF7ci remote_id: df6c28e8 name: backend type: team required: - id - remote_id - name - type properties: id: example: 4B9bKBpX5tnwjiG93TAqF7ci nullable: true type: string remote_id: example: '49' nullable: true type: string name: example: Customer Success nullable: true type: string type: example: TEAM nullable: true type: string enum: - - department - team - cost_centre - pay_group Groups20230301Response: type: array nullable: true example: - id: 4B9bKBpX5tnwjiG93TAqF7ci remote_id: df6c28e8 name: backend type: team - id: 132Xpnw2a38aaQG93TAqF7ci remote_id: 355c65922637 name: engineering type: department items: "$ref": "#/components/schemas/groupResponse" EmployeeResponse: type: object required: - id - remote_id - employee_number - first_name - last_name - display_full_name - nationality - job_title - work_email - personal_email - mobile_phone_number - tax_id - gender - ethnicity - marital_status - date_of_birth - employment_status - employment_type - start_date - remote_created_at - termination_date - avatar - home_location - work_location - manager - bank_account - employment_history - compensation_history - custom_fields - groups - dependents - emergency_contacts properties: id: description: The Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string readOnly: true remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string readOnly: true employee_number: nullable: true example: '2' type: string first_name: description: the first name of the individual example: Greg type: string last_name: description: the last name of the individual example: Hirsch type: string display_full_name: example: Hirsch nullable: true type: string nationality: example: Irish nullable: true type: string job_title: example: Software developer nullable: true type: string work_email: description: the work email of the individual example: greg@affixapi.com nullable: true type: string personal_email: description: the personal email of the individual example: greg@gmail.com nullable: true type: string mobile_phone_number: description: "+1234567890" example: Hirsch nullable: true type: string tax_id: example: '1234567890' nullable: true type: string gender: example: male nullable: true type: string enum: - male - female - not_specified - ethnicity: nullable: true example: white type: string enum: - - asian - black - hispanic - mixed - not_specified - other - white marital_status: nullable: true example: single type: string description: | `other` option can include co-habitating, civil partnership, separated, widowed, etc enum: - single - married - divorced - not_specified - other - date_of_birth: example: '1990-11-10' nullable: true type: string format: date employment_status: "$ref": "#/components/schemas/employment-statusResponse" employment_type: nullable: true example: full_time type: string enum: - - full_time - part_time - contractor - other start_date: example: '2020-10-11' nullable: true type: string format: date remote_created_at: example: '2020-10-11' nullable: true type: string format: date readOnly: true termination_date: example: '2021-10-12' nullable: true type: string format: date avatar: example: http://alturl.com/h2h8m nullable: true type: string home_location: "$ref": "#/components/schemas/addressResponse" work_location: "$ref": "#/components/schemas/locationResponse" manager: nullable: true type: object required: - first_name - last_name - id - work_email - remote_id properties: first_name: nullable: true type: string last_name: nullable: true type: string id: type: string description: | the Affix-assigned ID of the individual. Nullable if the system only reports the name of the manager; not their ID nullable: true work_email: nullable: true type: string remote_id: nullable: true type: string bank_account: nullable: true type: object required: - account_number - bank_name - bic - holder_name - iban properties: account_number: nullable: true type: string bank_name: nullable: true type: string bic: nullable: true type: string holder_name: nullable: true type: string iban: nullable: true type: string employment_history: nullable: true type: array items: "$ref": "#/components/schemas/employment-historyResponse" compensation_history: nullable: true type: array items: "$ref": "#/components/schemas/compensation-historyResponse" custom_fields: nullable: true type: object example: t_shirt_size: medium groups: "$ref": "#/components/schemas/Groups20230301Response" dependents: nullable: true type: array items: type: object required: - name - relationship properties: name: nullable: true type: string relationship: nullable: true type: string emergency_contacts: nullable: true type: array items: type: object required: - first_name - last_name - relationship - mobile_phone_number - primary_contact properties: first_name: nullable: true type: string last_name: nullable: true type: string relationship: nullable: true type: string mobile_phone_number: nullable: true type: string primary_contact: nullable: true type: boolean Employees20230301Response: type: array items: "$ref": "#/components/schemas/EmployeeResponse" IdentityResponse: type: object required: - name - email - phone_number properties: name: description: The name of the individual for the respective account, if known example: Laurine Barton type: string email: description: The email of the individual for the respective account, if known example: laurine.barton@me.com type: string phone_number: description: | The phone number of the individual for the respective account, if known. Nullable for tokens created prior to 2023-03-05 example: 14150000000 type: string nullable: true policy-typeResponse: type: string example: vacation enum: - - bereavement - holiday - jury_duty - personal - sick - vacation - volunteer nullable: true TimeOffEntryResponse: type: object required: - id - remote_id - employee_id - employee_remote_id - start_date - end_date - amount - unit - status - employee_note - policy_id - policy_remote_id - policy_name - policy_type - remote_created_at - remote_modified_at properties: id: description: The Affix-assigned id of the time off entry example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string remote_id: description: the remote system-assigned id of the time off entry example: '19202938' type: string employee_id: description: the Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string employee_remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string start_date: example: '2020-10-11' nullable: true type: string format: date end_date: example: '2020-10-14' nullable: true type: string format: date amount: type: number multipleOf: 0.1 example: 3 unit: type: string example: days enum: - - hours - days - months status: type: string nullable: true example: approved enum: - - approved - pending - rejected employee_note: type: string nullable: true example: Visiting my family policy_id: description: The Affix-assigned id of the policy example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true policy_remote_id: description: The remote system-assigned id of the policy example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true policy_name: description: The name of the policy, as assigned by the remote system type: string example: Comp/In Lieu Time nullable: true policy_type: "$ref": "#/components/schemas/policy-typeResponse" remote_created_at: example: '2020-10-11' nullable: true type: string format: date remote_modified_at: example: '2020-10-12' nullable: true type: string format: date TimeOffEntries20230301Response: type: array items: "$ref": "#/components/schemas/TimeOffEntryResponse" TimesheetResponse: type: object required: - id - remote_id - employee_id - employee_remote_id - start_time - end_time - hours_worked - remote_created_at - remote_modified_at properties: id: description: The Affix-assigned id of the time off entry example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string remote_id: description: the remote system-assigned id of the time off entry example: '19202938' type: string employee_id: description: the Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string employee_remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string start_time: example: '2020-10-11T08:00:00Z' nullable: true type: string format: date-time end_time: example: '2020-10-11T17:00:00Z' nullable: true type: string format: date-time hours_worked: type: number multipleOf: 0.1 example: 8 remote_created_at: example: '2020-10-11' nullable: true type: string format: date remote_modified_at: example: '2020-10-12' nullable: true type: string format: date Timesheets20230301Response: type: array items: "$ref": "#/components/schemas/TimesheetResponse" TimeOffBalanceResponse: type: object required: - employee_id - employee_remote_id - balance - used - policy_id - policy_remote_id - policy_type - policy_name - remote_created_at - remote_modified_at properties: employee_id: description: The Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string employee_remote_id: description: the remote system-assigned id of the individual example: '19202938' type: string balance: type: number nullable: true example: 24.5 used: type: number nullable: true example: 12 policy_id: description: The Affix-assigned id of the policy example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true policy_remote_id: description: The remote system-assigned id of the policy example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true policy_name: description: The name of the policy, as assigned by the remote system type: string example: Comp/In Lieu Time nullable: true policy_type: "$ref": "#/components/schemas/policy-typeResponse" remote_created_at: example: '2020-10-11' nullable: true type: string format: date remote_modified_at: example: '2020-10-11' nullable: true type: string format: date TimeOffBalances20230301Response: type: array items: "$ref": "#/components/schemas/TimeOffBalanceResponse" WorkLocations20230301Response: type: array description: Work locations items: "$ref": "#/components/schemas/locationResponse" payrun-typeResponse: nullable: true example: regular type: string enum: - regular - one_time - off_cycle - correction - reversal - PayrunResponse: type: object required: - id - remote_id - state - type - start_date - end_date - payment_date properties: id: description: The Affix-assigned id of the individual example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string remote_id: description: the remote system-assigned id of the payrun example: '19202938' type: string state: example: paid nullable: true type: string enum: - paid - pending - type: "$ref": "#/components/schemas/payrun-typeResponse" start_date: nullable: true example: '2020-01-01' type: string format: date description: Payrun period start date end_date: nullable: true example: '2020-01-31' type: string format: date description: Payrun period end date payment_date: nullable: true example: '2020-01-27' type: string format: date description: Payment date / check date Payruns20230301Response: type: array items: "$ref": "#/components/schemas/PayrunResponse" currency-not-nullResponse: type: string example: eur nullable: true enum: - usd - gbp - eur - sek - cad PayslipResponse: type: object required: - id - remote_id - employee_id - employee_remote_id - payrun_id - payrun_remote_id - payrun_type - currency - gross_pay - net_pay - start_date - end_date - payment_date - earnings - contributions - deductions - taxes - reimbursements properties: id: description: The Affix-assigned id of the payslip example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw type: string nullable: true remote_id: description: the remote system-assigned id of the payrun example: '19202938' type: string nullable: true employee_id: type: string example: d2f972d0-2526-434b-9409-4c3b468e08f0 employee_remote_id: type: string example: '19202938' payrun_id: type: string example: 35347df1-95e7-46e2-93cc-66f1191edca5 payrun_remote_id: type: string example: '19202938' payrun_type: "$ref": "#/components/schemas/payrun-typeResponse" currency: "$ref": "#/components/schemas/currency-not-nullResponse" gross_pay: type: number example: 134267 nullable: true description: if USD/EUR/GBP, in cent net_pay: type: number nullable: true description: if USD/EUR/GBP, in cent example: 86578 start_date: example: '2020-01-01' type: string format: date end_date: example: '2020-01-31' type: string format: date payment_date: example: '2020-01-27' type: string format: date earnings: type: array nullable: true example: - amount: 100234 name: SALARY hours: 80 - amount: 834234 name: OVERTIME hours: 8 items: type: object description: The breakdown of gross pay required: - name - amount - hours properties: name: type: string example: salary amount: type: number description: if USD/EUR/GBP, in cent example: 834234 hours: type: number description: hours, if applicable example: 80 nullable: true contributions: type: array example: - name: Private Health Insurance (Employer) amount: 13454 - name: Transportation allowance benefit (Employer) amount: 3454 - name: Other (Employer) amount: 3454 nullable: true description: | Items paid by the employer that are not included in gross pay, such as employer-paid portion of private health insurance items: type: object required: - name - amount properties: name: type: string example: Private Health Insurance (Employer) amount: type: number description: if USD/EUR/GBP, in cent example: 3454 deductions: type: array nullable: true example: - name: Transportation allowance benefit amount: 3454 - name: Private Health Insurance (Employee) amount: 3454 items: type: object required: - name - amount properties: name: type: string example: Private Insurance Premium (Employee) amount: type: number description: if USD/EUR/GBP, in cent example: 3454 taxes: type: array nullable: true example: - name: PRSI amount: 725 employer_tax: false - name: PSC (Class S) amount: 125 employer_tax: false - name: Income Tax amount: 10025 employer_tax: false - name: Payroll Tax amount: 10025 employer_tax: true items: type: object required: - name - amount - employer_tax properties: name: type: string example: Income Tax amount: type: number example: 10025 description: if USD/EUR/GBP, in cent employer_tax: type: boolean nullable: true reimbursements: type: array nullable: true example: - name: Slack seat amount: 725 items: type: object required: - name - amount properties: name: type: string example: Slack seat amount: type: number example: 10025 description: if USD/EUR/GBP, in cent Payslips20230301Response: type: array items: "$ref": "#/components/schemas/PayslipResponse"