Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
api:api_applicants [2014/06/29 20:32]
Lauri Elevant [Parameters]
api:api_applicants [2021/01/21 12:51] (current)
Line 5: Line 5:
 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 16384 items returned, which is capped to 512 if the ''expand'' parameter is used.
 ==== Syntax ==== ==== Syntax ====
  
Line 10: Line 11:
   Host: apply.example.edu   Host: apply.example.edu
   Authorization: DREAM apikey="..."   Authorization: DREAM apikey="..."
 +
  
 ==== Parameters ==== ==== Parameters ====
  
 ^ 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] |
 | ''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] |
 | ''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..16384, 16384 being the default). If the ''expand'' parameter is used, the limit is 512. | |
 +| ''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 [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 ====
  
Line 25: Line 34:
   Content-Length: 1456   Content-Length: 1456
   X-Count: 15   X-Count: 15
 +
 +
 +==== Response codes ====
 +
 +| ''400 Bad Request'' | One of the filters has bad parameters (see error description) |
 +
 +
 +==== Response example ====
 +
 +  {
 +    "123": {
 +        "registered": "2014-06-20T08:13:41+00:00",
 +        "name": {
 +            "given": "Joe",
 +            "middle": "",
 +            "family": "Smith"
 +        },
 +        "email": "sample.applicant.21@example.com",
 +        "skype": null,
 +        "phone": "+372 123456789",
 +        "reference": "foobar",
 +        "citizenship": "US",
 +        "trackers": "/api/applicants/123/trackers",
 +        "photo": "/api/applicants/123/photo",
 +        "documents": "/api/applicants/123/documents"
 +    }
 +  }
 +
 +===== POST =====
 +
 +Create a new applicant/lead. The owner of the new account will be notified via email, using the ''applicant-welcome-api'' template. The welcome letter will also contain the account credentials needed for the applicant to start using his/her new account. Please include any additional instructions in the template - you can configure all templates using the admin interface (look for the "Settings" -> "Templates" menu). 
 +
 +The URI for the new applicant account that was created is returned in the ''Location'' header.
 +
 +Note that since this API call will send an email before returning, it is slightly slower than other API calls. This is a deliberate choice to avoid storing the (secrets-containing) email in more intermediate queues than required, while also guaranteeing that if the call succeeds, the email was accepted upstream.
 +
 +If an applicant/lead with this email address exists, a ''409 Conflict'' will be returned, along with the URI of the offending applicant in the ''Location'' header.
 +
 +==== Syntax ====
 +
 +  POST /api/applicants
 +  Host: apply.example.edu
 +  Authorization: DREAM apikey="..."
 +  
 +==== Parameters ====
 +
 +^ Name ^  ^ Description ^
 +| ''email'' | **Required** | A valid email address. Must be unique (see above). |
 +| ''citizenship'' | Optional | This is optional, but highly recommended. The citizenship affect all deadlines/fees display for the applicant. If not provided, it will be asked when applicant is logging in. Accepts an [[http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country code]] |
 +| ''name'' | **Required** | Full name of the lead/applicant. 1 to 50 characters. You must provide either ''name'' or both ''name_given/family'' |
 +| ''name_given'' | **Required** | Given name of the lead/applicant. 1 to 50 characters. You must provide either ''name'' or both ''name_given/family''  |
 +| ''name_family'' | **Required** | Family name of the lead/applicant. 1 to 50 characters.  You must provide either ''name'' or both ''name_given/family'' |
 +| ''phone'' | Optional | Phone number of the lead/applicant, for example "+372 123456789". Up to 30 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]]|
 +
 +==== Response headers ====
 +
 +  Content-Type: application/json
 +  Content-Length: 0
 +  Location: /api/applicants/12345
 +
 +==== Response codes ====
 +
 +| ''201 Created'' | New applicant/lead was created |
 +| ''409 Conflict'' | An applicant with this email address already exists |