Managing EOR employment agreements

This guide will show you how to manage EOR employment agreements for employments using the Oyster API. The different agreements are:

Agreement name	Type	Required?	Description
Oyster Service agreements	`OYSTER_SERVICE_AGREEMENT`	Yes	The agreement between Oyster and the customer for each employment.
Employment Agreement	`EMPLOYMENT_AGREEMENT`	Yes	The employment agreement between Oyster and the employee.
Remote Work Schedule	`REMOTE_WORK`	No	This agreement can optionally be selected when creating and submitting the EOR employment (UI only).
Confidentiality and Intellectual Property Agreement	`CONFIDENTIALITY_AND_INTELLECTUAL_PROPERTY`	No	This agreement can optionally be selected when creating and submitting the EOR employment. This is included by default in employments created via API.
Restrictive Covenant Agreement	`RESTRICTIVE_COVENANT`	No	This agreement can optionally be selected when creating and submitting the EOR employment (UI only).

All the above agreements except the OYSTER_SERVICE_AGREEMENT require all onboarding to be completed before they can be verified. This can either be done in platform or using the Creating and submitting an EOR employment and Completing EOR employment onboarding guides.

Note for Reseller partners using the API - you will need to use the X-Oyster-Customer-Id header for all of the calls in this guide. For more information, see the Reseller guide to using the Oyster API.

1. Retrieve agreements for an employment

Before you can interact with individual agreements, you first need to retrieve a list of all agreements associated with a specific employment using the Retrieve all agreements for employment endpoint.

Example Request

curl --request GET \
     --url https://api.oysterhr.com/v0.1/hiring/employments/urY7zKOm/agreements \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

The response will contain a list of agreements associated with the employment, including agreement IDs that will be needed in the next steps. The response will also include the agreement state and url. A url is not available for agreements in the pending state.

Note: agreement ids are specific to the agreement version. If an agreement is changed, the id will become deprecated and a new id will be generated for the same agreement type.

Example Response

{
  "data": [
    {
      "id": "Secik2BS",
      "name": "Confidentiality and Intellectual Property Agreement",
      "type": "CONFIDENTIALITY_AND_INTELLECTUAL_PROPERTY",
      "state": "READY_TO_SIGN",
      "preview": {
        "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhjblJ0TUdSaGFHbGtlR3gyYm5FMk0zbGxaVE4wTVd3MWEzQjRlUVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpQVlCcGJteHBibVU3SUdacGJHVnVZVzFsUFNKamIyNW1hV1JsYm5ScFlXeHBkSGxmWVc1a1gybHVkR1ZzYkdWamRIVmhiRjl3Y205d1pYSjBlUzV3WkdZaU95Qm1hV3hsYm1GdFpTbzlWVlJHTFRnbkoyTnZibVpwWkdWdWRHbGhiR2wwZVY5aGJtUmZhVzUwWld4c1pXTjBkV0ZzWDNCeWIzQmxjblI1TG5Ca1pnWTdCbFE2RVdOdmJuUmxiblJmZEhsd1pVa2lGR0Z3Y0d4cFkyRjBhVzl1TDNCa1pnWTdCbFE2RVhObGNuWnBZMlZmYm1GdFpUb0pkR1Z6ZEE9PSIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--891285f78fcdbeda014119c9851c46d187886c7f/confidentiality_and_intellectual_property.pdf",
        "contentType": "application/pdf"
      }
    },
    {
      "id": "yfp7SoKW",
      "name": "Employment Agreement",
      "type": "EMPLOYMENT_AGREEMENT",
      "state": "DRAFT",
      "preview": {
        "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhlV3R1Y1RnNU5tOTRaVFpoWmpCME1tODJNVFJpWkRoc2EySmtNUVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpVzJsdWJHbHVaVHNnWm1sc1pXNWhiV1U5SW1WdGNHeHZlVzFsYm5SZllXZHlaV1Z0Wlc1MExuQmtaaUk3SUdacGJHVnVZVzFsS2oxVlZFWXRPQ2NuWlcxd2JHOTViV1Z1ZEY5aFozSmxaVzFsYm5RdWNHUm1CanNHVkRvUlkyOXVkR1Z1ZEY5MGVYQmxTU0lVWVhCd2JHbGpZWFJwYjI0dmNHUm1CanNHVkRvUmMyVnlkbWxqWlY5dVlXMWxPZ2wwWlhOMCIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--5f6c5bcb7bc9c2a83314b7cd4e88f7f0c4d94d4b/employment_agreement.pdf",
        "contentType": "application/pdf"
      }
    },
    {
      "id": "zAol69ON",
      "name": "Oyster Service Agreement",
      "type": "OYSTER_SERVICE_AGREEMENT",
      "state": "SIGNED",
      "preview": {
        "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhZbWswTUdOM2RURXplVEpqZEdGMU5XazFkMk55ZG5SdVpqWnNjUVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpWTJsdWJHbHVaVHNnWm1sc1pXNWhiV1U5SW05NWMzUmxjbDl6WlhKMmFXTmxYMkZuY21WbGJXVnVkQzV3WkdZaU95Qm1hV3hsYm1GdFpTbzlWVlJHTFRnbkoyOTVjM1JsY2w5elpYSjJhV05sWDJGbmNtVmxiV1Z1ZEM1d1pHWUdPd1pVT2hGamIyNTBaVzUwWDNSNWNHVkpJaFJoY0hCc2FXTmhkR2x2Ymk5d1pHWUdPd1pVT2hGelpYSjJhV05sWDI1aGJXVTZDWFJsYzNRPSIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--1a55a5eda382483c2a0a6ebad6e6cf8e846e2851/oyster_service_agreement.pdf",
        "contentType": "application/pdf"
      }
    },
    {
      "id": "HMNcgIHy",
      "name": "Remote Work Schedule",
      "type": "REMOTE_WORK",
      "state": "DRAFT",
      "preview": {
        "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhObXRzYW1jM2REVm5OV2h6TVhNMGVHMXJjV2g2WjNabE5YRm1jQVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpU1dsdWJHbHVaVHNnWm1sc1pXNWhiV1U5SW5KbGJXOTBaVjkzYjNKckxuQmtaaUk3SUdacGJHVnVZVzFsS2oxVlZFWXRPQ2NuY21WdGIzUmxYM2R2Y21zdWNHUm1CanNHVkRvUlkyOXVkR1Z1ZEY5MGVYQmxTU0lVWVhCd2JHbGpZWFJwYjI0dmNHUm1CanNHVkRvUmMyVnlkbWxqWlY5dVlXMWxPZ2wwWlhOMCIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--aa45396c236570287976bf45ddd809af74b79506/remote_work.pdf",
        "contentType": "application/pdf"
      }
    },
    {
      "id": "1L4sIgzU",
      "name": "Restrictive Covenant Agreement",
      "type": "RESTRICTIVE_COVENANT",
      "state": "PENDING"
    }
  ],
  "meta": {
    "items": 100,
    "count": 5,
    "page": 1,
    "pages": 1,
    "firstUrl": "/v0.1/hiring/employments/IcPSdGdh/agreements?perPage=100&page=1",
    "lastUrl": "/v0.1/hiring/employments/IcPSdGdh/agreements?perPage=100&page=1",
    "pageUrl": "/v0.1/hiring/employments/IcPSdGdh/agreements?perPage=100&page=1",
    "nextUrl": "/v0.1/hiring/employments/IcPSdGdh/agreements?perPage=100&page=",
    "prevUrl": "/v0.1/hiring/employments/IcPSdGdh/agreements?perPage=100&page="
  }
}

Once you have the list of agreements, you can also retrieve the details of a specific agreement by using its agreement_id using the Retrieve an individual agreement endpoint.

Example Request

curl --request GET \
     --url https://api.oysterhr.com/v0.1/hiring/employments/urY7zKOm/agreements/Z1tadFBB \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Example Response

{
  "data": {
    "id": "Z1tadFBB",
    "name": "Employment Agreement",
    "type": "EMPLOYMENT_AGREEMENT",
    "state": "DRAFT",
    "preview": {
      "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhNSFJyYTNoaFl6Y3dabXBoZW5CdGFtTjRNR1Y1WmpscU56TjNOd1k2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpVzJsdWJHbHVaVHNnWm1sc1pXNWhiV1U5SW1WdGNHeHZlVzFsYm5SZllXZHlaV1Z0Wlc1MExuQmtaaUk3SUdacGJHVnVZVzFsS2oxVlZFWXRPQ2NuWlcxd2JHOTViV1Z1ZEY5aFozSmxaVzFsYm5RdWNHUm1CanNHVkRvUlkyOXVkR1Z1ZEY5MGVYQmxTU0lVWVhCd2JHbGpZWFJwYjI0dmNHUm1CanNHVkRvUmMyVnlkbWxqWlY5dVlXMWxPZ2wwWlhOMCIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--f7179cbad211970d9f4fd4883ad4d8d6a564da35/employment_agreement.pdf",
      "contentType": "application/pdf"
    }
  }
}

2. Verify Agreements and send for signature

You can then use the Verify agreements endpoint, which will verify the agreements so they can be sent out for signature.

Note: agreement ids are specific to the agreement version. If an agreement is changed, the id will become deprecated and a new id will be generated for the same agreement type. An error response will be returned if verifying an obsolete version.

Example Request

curl --request POST \
     --url https://api.oysterhr.com/v0.1/hiring/employments/urY7zKOm/agreements/Z1tadFBB/verify \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

A successful request will return the agreement data with a state of VERIFIED.

In addition to the state change, once you verify the OYSTER_SERVICE_AGREEMENT the agreement is immediately sent to the customer for signature and the employee is invited to the platform if they haven’t already been invited.

Example Response

{
  "data": {
    "id": "Z1tadFBB",
    "name": "Employment Agreement",
    "type": "EMPLOYMENT_AGREEMENT",
    "state": "VERIFIED",
    "preview": {
      "url": "http://api.example.com/files/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhkbmxyWWpsb2QzQnlkekpwZWpaMmREbHBPV2c0ZDJaMmFqRnpkQVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpVzJsdWJHbHVaVHNnWm1sc1pXNWhiV1U5SW1WdGNHeHZlVzFsYm5SZllXZHlaV1Z0Wlc1MExuQmtaaUk3SUdacGJHVnVZVzFsS2oxVlZFWXRPQ2NuWlcxd2JHOTViV1Z1ZEY5aFozSmxaVzFsYm5RdWNHUm1CanNHVkRvUlkyOXVkR1Z1ZEY5MGVYQmxTU0lVWVhCd2JHbGpZWFJwYjI0dmNHUm1CanNHVkRvUmMyVnlkbWxqWlY5dVlXMWxPZ2wwWlhOMCIsImV4cCI6IjIwMjItMTAtMTVUMTI6Mzk6NTYuMDAwWiIsInB1ciI6ImJsb2Jfa2V5In19--aaa53e2cbd817ba14c6fb06270d373dcc6be3f24/employment_agreement.pdf",
      "contentType": "application/pdf"
    }
  }
}

3. Sending agreements for signature

Once certain conditions are met, documents can be sent for signature. This happens once the conditions are met without the need for any additional API call.

OYSTER_SERVICE_AGREEMENT - The agreement is immediately sent to the customer for signature once the agreement is verified.
The other employment agreements (EMPLOYMENT_AGREEMENT and the REMOTE_WORK, CONFIDENTIALITY_AND_INTELLECTUAL_PROPERTY, and RESTRICTIVE_COVENANT as applicable) will be sent for signature to the respective parties (customer and/or employee) once
- All available agreements have been verified
- The OYSTER_SERVICE_AGREEMENT has been signed
- The onboarding form has been submitted (either by the employee in the platform or via API by following the Completing EOR employment onboarding guide)
- The employment country is listed in the list of eSignature countries in the Hiring API country coverage guide.

Conclusion

Once all employment agreements have been signed, the employment will be ready to start work on the start date. From this point on, any additional employment related changes will need to be handled using the contract changes API.