openapi: 3.1.0 info: title: Accounting subpackage_candidates API version: 1.0.0 servers: - url: https://api.merge.dev/api - url: https://api-eu.merge.dev/api - url: https://api-ap.merge.dev/api tags: - name: subpackage_candidates paths: /ats/v1/candidates: get: operationId: list summary: List description: Returns a list of `Candidate` objects.{/* BEGIN_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: created_after in: query description: If provided, will only return objects created after this datetime. required: false schema: type: string format: date-time - name: created_before in: query description: If provided, will only return objects created before this datetime. required: false schema: type: string format: date-time - name: cursor in: query description: The pagination cursor value. required: false schema: type: string - name: email_addresses in: query description: If provided, will only return candidates with these email addresses; multiple addresses can be separated by commas. required: false schema: type: string - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/CandidatesGetParametersExpandSchemaItems' - name: first_name in: query description: If provided, will only return candidates with this first name. required: false schema: type: string - name: include_deleted_data in: query description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). required: false schema: type: boolean - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: last_name in: query description: If provided, will only return candidates with this last name. required: false schema: type: string - name: modified_after in: query description: If provided, only objects synced by Merge after this date time will be returned. required: false schema: type: string format: date-time - name: modified_before in: query description: If provided, only objects synced by Merge before this date time will be returned. required: false schema: type: string format: date-time - name: page_size in: query description: Number of results to return per page. The maximum limit is 100. required: false schema: type: integer - name: remote_id in: query description: The API provider's ID for the given object. required: false schema: type: string - name: tags in: query description: If provided, will only return candidates with these tags; multiple tags can be separated by commas. required: false schema: type: string - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PaginatedCandidateList' post: operationId: create summary: Create description: Creates a `Candidate` object with the given values.{/* BEGIN_ATS_CANDIDATE_CREATE_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_CREATE_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: is_debug_mode in: query description: Whether to include debug fields (such as log file links) in the response. required: false schema: type: boolean - name: run_async in: query description: Whether or not third-party updates should be run asynchronously. required: false schema: type: boolean - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CandidateResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/CandidateEndpointRequest' /ats/v1/candidates/{id}: get: operationId: retrieve summary: Retrieve description: Returns a `Candidate` object with the given `id`.{/* BEGIN_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: id in: path required: true schema: type: string format: uuid - name: expand in: query description: Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/CandidatesIdGetParametersExpandSchemaItems' - name: include_remote_data in: query description: Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_shell_data in: query description: Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Candidate' patch: operationId: partial-update summary: Partial Update description: Updates a `Candidate` object with the given `id`.{/* BEGIN_ATS_CANDIDATE_EDIT_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_EDIT_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: id in: path required: true schema: type: string format: uuid - name: is_debug_mode in: query description: Whether to include debug fields (such as log file links) in the response. required: false schema: type: boolean - name: run_async in: query description: Whether or not third-party updates should be run asynchronously. required: false schema: type: boolean - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CandidateResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedCandidateEndpointRequest' /ats/v1/candidates/ignore/{model_id}: post: operationId: ignore-create summary: Ignore Create description: Ignores a specific row based on the `model_id` in the url. These records will have their properties set to null, and will not be updated in future syncs. The "reason" and "message" fields in the request body will be stored for audit purposes.{/* BEGIN_ATS_CANDIDATE_CREATE_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_CREATE_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: model_id in: path required: true schema: type: string format: uuid - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: No response body content: application/json: schema: $ref: '#/components/schemas/candidates_ignoreCreate_Response_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/IgnoreCommonModelRequest' /ats/v1/candidates/meta/patch/{id}: get: operationId: meta-patch-retrieve summary: Meta Patch Retrieve description: Returns metadata for `Candidate` PATCHs.{/* BEGIN_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: id in: path required: true schema: type: string format: uuid - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/MetaResponse' /ats/v1/candidates/meta/post: get: operationId: meta-post-retrieve summary: Meta Post Retrieve description: Returns metadata for `Candidate` POSTs.{/* BEGIN_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */}{/* END_ATS_CANDIDATE_FETCH_SUPPORTED_FIELDS */} tags: - subpackage_candidates parameters: - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/MetaResponse' components: schemas: UrlTypeEnum: type: string enum: - PERSONAL - COMPANY - PORTFOLIO - BLOG - SOCIAL_MEDIA - OTHER - JOB_POSTING title: UrlTypeEnum candidates_ignoreCreate_Response_200: type: object properties: {} description: Empty response body title: candidates_ignoreCreate_Response_200 ErrorValidationProblem: type: object properties: source: $ref: '#/components/schemas/ValidationProblemSource' title: type: string detail: type: string problem_type: type: string block_merge_link: type: boolean raw_error: type: string error_code: type: integer required: - title - detail - problem_type title: ErrorValidationProblem CandidateEndpointRequest: type: object properties: model: $ref: '#/components/schemas/CandidateRequest' remote_user_id: type: string required: - model - remote_user_id title: CandidateEndpointRequest UrlRequest: type: object properties: value: type: - string - 'null' format: uri description: The site's url. url_type: oneOf: - $ref: '#/components/schemas/UrlTypeEnum' - type: 'null' description: The type of site. integration_params: type: - object - 'null' additionalProperties: description: Any type linked_account_params: type: - object - 'null' additionalProperties: description: Any type description: '# The Url Object ### Description The `Url` object is used to represent hyperlinks associated with the parent model. ### Usage Example Fetch from the `GET Candidate` endpoint and view their website urls.' title: UrlRequest EmailAddress: type: object properties: created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. value: type: - string - 'null' format: email description: The email address. email_address_type: oneOf: - $ref: '#/components/schemas/EmailAddressTypeEnum' - type: 'null' description: The type of email address. remote_was_deleted: type: boolean description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). description: '# The EmailAddress Object ### Description The `EmailAddress` object is used to represent a candidate''s email address. ### Usage Example Fetch from the `GET Candidate` endpoint and view their email addresses.' title: EmailAddress CandidatesGetParametersExpandSchemaItems: type: string enum: - applications - attachments title: CandidatesGetParametersExpandSchemaItems PatchedCandidateRequest: type: object properties: first_name: type: - string - 'null' description: The candidate's first name. last_name: type: - string - 'null' description: The candidate's last name. company: type: - string - 'null' description: The candidate's current company. title: type: - string - 'null' description: The candidate's current title. last_interaction_at: type: - string - 'null' format: date-time description: When the most recent interaction with the candidate occurred. is_private: type: - boolean - 'null' description: Whether or not the candidate is private. can_email: type: - boolean - 'null' description: Whether or not the candidate can be emailed. locations: type: - array - 'null' items: type: string description: The candidate's locations. phone_numbers: type: array items: $ref: '#/components/schemas/PhoneNumberRequest' email_addresses: type: array items: $ref: '#/components/schemas/EmailAddressRequest' urls: type: array items: $ref: '#/components/schemas/UrlRequest' tags: type: array items: type: string description: Array of `Tag` names as strings. applications: type: array items: type: string format: uuid description: Array of `Application` object IDs. attachments: type: array items: type: string format: uuid description: Array of `Attachment` object IDs. remote_template_id: type: - string - 'null' integration_params: type: - object - 'null' additionalProperties: description: Any type linked_account_params: type: - object - 'null' additionalProperties: description: Any type description: '# The Candidate Object ### Description The `Candidate` object is used to represent profile information about a given Candidate. Because it is specific to a Candidate, this information stays constant across applications. ### Usage Example Fetch from the `LIST Candidates` endpoint and filter by `ID` to show all candidates.' title: PatchedCandidateRequest Candidate: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. first_name: type: - string - 'null' description: The candidate's first name. last_name: type: - string - 'null' description: The candidate's last name. company: type: - string - 'null' description: The candidate's current company. title: type: - string - 'null' description: The candidate's current title. remote_created_at: type: - string - 'null' format: date-time description: When the third party's candidate was created. remote_updated_at: type: - string - 'null' format: date-time description: When the third party's candidate was updated. last_interaction_at: type: - string - 'null' format: date-time description: When the most recent interaction with the candidate occurred. is_private: type: - boolean - 'null' description: Whether or not the candidate is private. can_email: type: - boolean - 'null' description: Whether or not the candidate can be emailed. locations: type: - array - 'null' items: type: string description: The candidate's locations. phone_numbers: type: array items: $ref: '#/components/schemas/PhoneNumber' email_addresses: type: array items: $ref: '#/components/schemas/EmailAddress' urls: type: array items: $ref: '#/components/schemas/Url' tags: type: array items: type: string description: Array of `Tag` names as strings. applications: type: array items: type: string format: uuid description: Array of `Application` object IDs. attachments: type: array items: type: string format: uuid description: Array of `Attachment` object IDs. remote_was_deleted: type: boolean description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/CandidateFieldMappings' - type: 'null' remote_data: type: - array - 'null' items: $ref: '#/components/schemas/RemoteData' description: '# The Candidate Object ### Description The `Candidate` object is used to represent profile information about a given Candidate. Because it is specific to a Candidate, this information stays constant across applications. ### Usage Example Fetch from the `LIST Candidates` endpoint and filter by `ID` to show all candidates.' title: Candidate CandidateRequest: type: object properties: first_name: type: - string - 'null' description: The candidate's first name. last_name: type: - string - 'null' description: The candidate's last name. company: type: - string - 'null' description: The candidate's current company. title: type: - string - 'null' description: The candidate's current title. last_interaction_at: type: - string - 'null' format: date-time description: When the most recent interaction with the candidate occurred. is_private: type: - boolean - 'null' description: Whether or not the candidate is private. can_email: type: - boolean - 'null' description: Whether or not the candidate can be emailed. locations: type: - array - 'null' items: type: string description: The candidate's locations. phone_numbers: type: array items: $ref: '#/components/schemas/PhoneNumberRequest' email_addresses: type: array items: $ref: '#/components/schemas/EmailAddressRequest' urls: type: array items: $ref: '#/components/schemas/UrlRequest' tags: type: array items: type: string description: Array of `Tag` names as strings. applications: type: array items: type: string format: uuid description: Array of `Application` object IDs. attachments: type: array items: type: string format: uuid description: Array of `Attachment` object IDs. remote_template_id: type: - string - 'null' integration_params: type: - object - 'null' additionalProperties: description: Any type linked_account_params: type: - object - 'null' additionalProperties: description: Any type description: '# The Candidate Object ### Description The `Candidate` object is used to represent profile information about a given Candidate. Because it is specific to a Candidate, this information stays constant across applications. ### Usage Example Fetch from the `LIST Candidates` endpoint and filter by `ID` to show all candidates.' title: CandidateRequest WarningValidationProblem: type: object properties: source: $ref: '#/components/schemas/ValidationProblemSource' title: type: string detail: type: string problem_type: type: string block_merge_link: type: boolean raw_error: type: string error_code: type: integer required: - title - detail - problem_type title: WarningValidationProblem PhoneNumberRequest: type: object properties: value: type: - string - 'null' description: The phone number. phone_number_type: oneOf: - $ref: '#/components/schemas/PhoneNumberTypeEnum' - type: 'null' description: The type of phone number. integration_params: type: - object - 'null' additionalProperties: description: Any type linked_account_params: type: - object - 'null' additionalProperties: description: Any type description: '# The PhoneNumber Object ### Description The `PhoneNumber` object is used to represent a candidate''s phone number. ### Usage Example Fetch from the `GET Candidate` endpoint and view their phone numbers.' title: PhoneNumberRequest PhoneNumber: type: object properties: created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. value: type: - string - 'null' description: The phone number. phone_number_type: oneOf: - $ref: '#/components/schemas/PhoneNumberTypeEnum' - type: 'null' description: The type of phone number. remote_was_deleted: type: boolean description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). description: '# The PhoneNumber Object ### Description The `PhoneNumber` object is used to represent a candidate''s phone number. ### Usage Example Fetch from the `GET Candidate` endpoint and view their phone numbers.' title: PhoneNumber CandidateFieldMappings: type: object properties: organization_defined_targets: type: object additionalProperties: description: Any type linked_account_defined_targets: type: object additionalProperties: description: Any type title: CandidateFieldMappings DebugModeLog: type: object properties: log_id: type: string dashboard_view: type: string log_summary: $ref: '#/components/schemas/DebugModelLogSummary' required: - log_id - dashboard_view - log_summary title: DebugModeLog ReasonEnum: type: string enum: - GENERAL_CUSTOMER_REQUEST - GDPR - OTHER title: ReasonEnum MetaResponse: type: object properties: request_schema: type: object additionalProperties: description: Any type status: $ref: '#/components/schemas/LinkedAccountStatus' has_conditional_params: type: boolean has_required_linked_account_params: type: boolean remote_fields: type: array items: type: string format: uuid description: Remote field values to populate required: - request_schema - has_conditional_params - has_required_linked_account_params title: MetaResponse Url: type: object properties: created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. value: type: - string - 'null' format: uri description: The site's url. url_type: oneOf: - $ref: '#/components/schemas/UrlTypeEnum' - type: 'null' description: The type of site. remote_was_deleted: type: boolean description: Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). description: '# The Url Object ### Description The `Url` object is used to represent hyperlinks associated with the parent model. ### Usage Example Fetch from the `GET Candidate` endpoint and view their website urls.' title: Url IgnoreCommonModelRequest: type: object properties: reason: $ref: '#/components/schemas/ReasonEnum' message: type: string required: - reason title: IgnoreCommonModelRequest EmailAddressTypeEnum: type: string enum: - PERSONAL - WORK - OTHER title: EmailAddressTypeEnum PatchedCandidateEndpointRequest: type: object properties: model: $ref: '#/components/schemas/PatchedCandidateRequest' remote_user_id: type: string required: - model - remote_user_id title: PatchedCandidateEndpointRequest PhoneNumberTypeEnum: type: string enum: - HOME - WORK - MOBILE - SKYPE - OTHER title: PhoneNumberTypeEnum RemoteData: type: object properties: path: type: string description: The third-party API path that is being called. data: description: The data returned from the third-party for this object in its original, unnormalized format. required: - path description: '# The RemoteData Object ### Description The `RemoteData` object is used to represent the full data pulled from the third-party API for an object. ### Usage Example TODO' title: RemoteData ValidationProblemSource: type: object properties: pointer: type: string required: - pointer title: ValidationProblemSource CandidatesIdGetParametersExpandSchemaItems: type: string enum: - applications - attachments title: CandidatesIdGetParametersExpandSchemaItems CandidateResponse: type: object properties: model: $ref: '#/components/schemas/Candidate' warnings: type: array items: $ref: '#/components/schemas/WarningValidationProblem' errors: type: array items: $ref: '#/components/schemas/ErrorValidationProblem' logs: type: array items: $ref: '#/components/schemas/DebugModeLog' required: - model - warnings - errors title: CandidateResponse PaginatedCandidateList: type: object properties: next: type: - string - 'null' previous: type: - string - 'null' results: type: array items: $ref: '#/components/schemas/Candidate' title: PaginatedCandidateList DebugModelLogSummary: type: object properties: url: type: string method: type: string status_code: type: integer required: - url - method - status_code title: DebugModelLogSummary LinkedAccountStatus: type: object properties: linked_account_status: type: string can_make_request: type: boolean required: - linked_account_status - can_make_request title: LinkedAccountStatus EmailAddressRequest: type: object properties: value: type: - string - 'null' format: email description: The email address. email_address_type: oneOf: - $ref: '#/components/schemas/EmailAddressTypeEnum' - type: 'null' description: The type of email address. integration_params: type: - object - 'null' additionalProperties: description: Any type linked_account_params: type: - object - 'null' additionalProperties: description: Any type description: '# The EmailAddress Object ### Description The `EmailAddress` object is used to represent a candidate''s email address. ### Usage Example Fetch from the `GET Candidate` endpoint and view their email addresses.' title: EmailAddressRequest securitySchemes: tokenAuth: type: http scheme: bearer description: Token-based authentication with required prefix "Bearer"