Extend write endpoints

​

Overview

Kombo supports a feature called Remote Fields for many write endpoints. This feature solves a similar problem as the passthrough API while still allowing you to use the unified Kombo API.

​

How does it help you

While we always try to solve even niche use cases with our unified API, there are cases where an integration requires particular data (for example, because your customer uses required custom fields or customizes their system a lot). In these cases, the remote fields feature allows you to pass this data to the connected system.

Remote fields also allow you to customize specific endpoints even more, as it would be out of scope for the unified model.

​

How to use it

Write actions that support this feature support have a property called remote_fields on the root level request body. This object follows a record structure where the key is the name of the tool (e.g., greenhouse), and the value is an object highly specific to the tool. On a high level, most available fields are documented in the endpoint specification.

A good example for a write endpoint supporting this feature, is the ATS API endpoint to create a new application (search for ‘remote fields’).

​

Example

A SuccessFactors instance requires the nationality of applicants as an attribute. nationality isn’t an attribute that is ordinarily supported by our ‘Create application’ endpoint. Because application creation generally works the same otherwise, you can use remote_fields to extend the requests that we send to SuccessFactors with the nationality field.

​

Remote fields in practice

You will likely find out about any required remote fields during testing. You may try to submit a dummy candidate, however, you receive an error message like the following:

{'status': 'error', 'error': {'message': {'remote_http_status': 500, 'remote_error': {'error': {'code': 'COE_GENERAL_SERVER_FAILURE', 'message': {'lang': 'en-US', 'value': '[COE0019]Unexpected error occurred: custNationality required for external candidate, custFutSponsor required for external candidate as per field override,  for templateId 579 ,  with the index 0'}}}}}}

For example, for the above error message, you would then need to add the following fields to your create candidate call for the parameter remote_fields:

{
    "successfactors": {
        "Candidate": {
            "custNationality": "some-nationality",
            "custFutSponsor": "some-sponsor"
        }
    }
}

You can then use an iterative process based on the error messages (“trial-and-error”) to tell whether you are now submitting the correct remote fields.

​

Help

Don’t hesitate to contact us if you have any questions about this feature or you need help with a specific use case.