Extend write endpoints
Learn how Kombo allows you to write additional, otherwise unsupported fields with unified write actions.
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 of 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.