| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| api:api_applicants [2020/10/14 13:53] – [Parameters] Lauri | api:api_applicants [2024/07/30 11:50] (current) – external edit 127.0.0.1 |
|---|
| List applicants using the filters set as parameters. The number of applicants is represented in the ''X-Count'' header - use the ''HEAD'' request to simply count the number of applicants matching the filters. Use the ''GET'' request to actually fetch them. | List applicants using the filters set as parameters. The number of applicants is represented in the ''X-Count'' header - use the ''HEAD'' request to simply count the number of applicants matching the filters. Use the ''GET'' request to actually fetch them. |
| |
| There is a hard limit of 8192 items returned, which is capped to 512 if the ''expand'' parameter is used. | There is a hard limit of 32768 items returned, which is capped to 8192 if the ''expand'' parameter is used. |
| ==== Syntax ==== | ==== Syntax ==== |
| |
| |
| ^ Name ^ ^ Description ^ Notes ^ | ^ Name ^ ^ Description ^ Notes ^ |
| | | ''bySince'' | Optional | An ISO datetime or the (sequential) ID from which you want to start fetching from (inclusive) | [4] | |
| | | ''byUntil'' | Optional | An ISO datetime or the (sequential) ID up to which to fetch to (inclusive) | [4] | |
| | ''byCitizenships'' | Optional | List of [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]] | [1] | | | ''byCitizenships'' | Optional | List of [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]] | [1] | |
| | ''byEmails'' | Optional | List of emails | [1] | | | ''byEmails'' | Optional | List of emails | [1] | |
| | ''byTrackerIDs'' | Optional | List of [[api:api_applicants_trackers|tracker ID-s]] | [1] [2] | | | ''byTrackerIDs'' | Optional | List of [[api:api_applicants_trackers|tracker ID-s]] | [1] [2] | |
| | ''byTrackerCodes'' | Optional | List of [[api:api_applicants_trackers|tracker codes]] | [1] [2] | | | ''byTrackerCodes'' | Optional | List of [[api:api_applicants_trackers|tracker codes]] | [1] [2] | |
| | ''limit'' | Optional | How many applicants to return (Allowed range is normally 1..8192, 8192 being the default). If the ''expand'' parameter is used, the limit is 512. If the amount of filtered records exceeds the limit, an error is returned. | | | | ''limit'' | Optional | How many applicants to return (Allowed range is normally 1..32768, 32768 being the default). If the ''expand'' parameter is used, the limit is 8192. | | |
| | ''expand'' | Optional | Expand the chosen relational element(s), for example ''applicant,offer'' | [3] | | | ''expand'' | Optional | Expand the chosen relational element(s), for example ''applicant,offer'' | [3] | |
| |
| * // Note [1]: Lists can be either comma or space separated. All list items are combined with logical ''OR'' operators - in other words an application is considered matching if it matches to any of the values in the list.// | * // Note [1]: Lists can be either comma or space separated. All list items are combined with logical ''OR'' operators - in other words an application is considered matching if it matches to any of the values in the list.// |
| * // Note [2]: you may use either tracker ID-s or codes to reference trackers. However ID-s are guaranteed not to change while the tracker codes offer no such guarantee. // | * // Note [2]: you may use either tracker ID-s or codes to reference trackers. However ID-s are guaranteed not to change while the tracker codes offer no such guarantee. // |
| * // Note [3]: Some elements in the returned objects are links to other API calls. Using the ''expand'' parameter, it is possible to expand this data to the actual records, saving additional API calls. The full list of possible expansions is ''trackers,documents,consents,invoices,wishes''. You can set one or multiple expansions, combining them in a comma-separated fashion to the ''expand'' parameter. Note also that using this parameter caps to ''limit'' to 512 due to performance reasons.// | * // Note [3]: Some elements in the returned objects are links to other API calls. Using the ''expand'' parameter, it is possible to expand this data to the actual records, saving additional API calls. The full list of possible expansions is ''trackers,documents,consents,invoices,wishes''. You can set one or multiple expansions, combining them in a comma-separated fashion to the ''expand'' parameter. Note also that using this parameter caps to ''limit'' to 8192 due to performance reasons.// |
| | * // Note [4]: An [[https://en.wikipedia.org/wiki/ISO_8601|ISO 8601 compatible datetime]] (inclusive) or the applicant ID to start from (inclusive). The date is applied to the registration time of the applicant, so you can only fetch applicants registered in the last N days, weeks or months. The applicant ID-s are sequential integers, so you can simply save the last applicant ID you processed, and issue the next call with bySince=$lastID+1// |
| |
| ==== Response headers ==== | ==== Response headers ==== |
| | ''notes'' | Optional | Any notes accompanying the lead/applicant. Up to 2048 characters. | | | ''notes'' | Optional | Any notes accompanying the lead/applicant. Up to 2048 characters. | |
| | ''reference'' | Optional | A reference code (often an external ID). Can also be managed individually, [[api:api_applicants_id_reference|read more]]| | | ''reference'' | Optional | A reference code (often an external ID). Can also be managed individually, [[api:api_applicants_id_reference|read more]]| |
| | | ''matriculation'' | Optional | A matriculation number. Can also be managed individually, [[api:api_applicants_id_matriculation|read more]]| |
| | | ''tracker_ID'' | Optional | ID of a tracker object to be associated with the applicant. | |
| |
| ==== Response headers ==== | ==== Response headers ==== |