Batch Designations

Update designation decisions for a set of applicants in a single API request using a batch action. A batch action is an asynchronous operation that can be created using a first endpoint and then have its result checked using another endpoint. First the batch action is created using the POST (create) endpoint by sending in the request body, the JSON describing all the changes to apply. The creation endpoint validates the changes and then schedules the batch to be executed returning a batch id to check the result later on. Then the GET (show) endpoint can be used to check the completion of the scheduled batch, using the id returned by the previous POST. Once the batch has finished, the result will be included in the batch object.

Attributes

Name	Type	Description	Example
batch:id	integer	Unique identifier of this batch.	74780
batch:results/applicant_cas_id	string	The CAS unique identifier of the applicant.	"123456789"
batch:results/decision:id	integer	The unique identifier for the decision to set. If the designation is in received status and the preliminary_data_handling feature is on, the code will prevent changes to the decision code.	99
batch:results/decision:name	string	Human-readable name for this decision.	"example"
batch:results/errors	nullable object		null
batch:results/errors:applicant	string	An error message indicating that the applicant_cas_id provided was invalid.	"No applicant found for that applicant_cas_id"
batch:results/errors:creation_error	string	A message explaining why a change could not be completed.	"A newer update (setting decision_id to 4698) is overriding this update"
batch:results/errors:decision	string	An error message indicating that the decision_id provided was invalid.	"No decision found for that decision_id"
batch:results/errors:designation	string	An error message indicating that no designation was found for the given applicant and program.	"No designation found for the given applicant and program"
batch:results/errors:update_error	string	An error message explaining why the update could not be applied.	"ActiveRecord::ConnectionNotEstablished"
batch:status	string	Current status of this batch. one of:"Queued" or "In Progress" or "Available" or "Success With Errors" or "Failed"	"Available"
href	string	Hypertext reference to the batch. pattern: /api/v2/user_identities/\d+/programs/\d+/batch_designations/\d+	"/api/v2/user_identities/1/programs/42023191739237/batch_designations/74780"

Batch Designations Show

Retrieve the status of a running/done batch action initiated with a previous POST. The id parameter is required. It is the id of the batch that you wish to check the status of. You may continue to issue this call over a reasonable polling interval (10s) until the batch has finished. Once the status of the batch becomes "Available", the detailed information of the modification applied will be in the "result" property of the batch object in the response.

GET /api/v2/user_identities/:user_identity_id/programs/:program_id/batch_designations/:id

Required Parameters

Name	Type	Description	Example
id	integer	Unique identifier of this batch.	74780

Curl Example

$ curl -n https://api.webadmit.org/api/v2/user_identities/:user_identity_id/programs/:program_id/batch_designations/:id \
 -G \
  -d id=74780 \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 200 OK

{
  "href": "/api/v2/user_identities/1/programs/42023191739237/batch_designations/74780",
  "batch": {
    "id": 74780,
    "status": "Available",
    "results": [
      {
        "decision": {
          "id": 4697,
          "name": "Matriculated"
        },
        "applicant_cas_id": "1595659994",
        "errors": {
          "creation_error": "A newer update (setting decision_id to 4698) is overriding this update"
        }
      },
      {
        "decision": {
          "id": 420,
          "name": "Unknown"
        },
        "applicant_cas_id": "1595659995",
        "errors": {
          "decision": "No decision found for that decision_id",
          "applicant": "No applicant found for that applicant_cas_id"
        }
      },
      {
        "decision": {
          "id": 4698,
          "name": "Redirected"
        },
        "applicant_cas_id": "1595659994",
        "errors": null
      }
    ]
  }
}

Batch Designations Create

Schedule the update of multiple designations with the given applicant CAS IDs and program ID, by creating a batch. WARNING: You'll get an error when you're trying to set a decision_id to a designation which already has a local status assigned. If you want to be able to force the decision_id please contact Liaison to turn on the "Disassociate Decision Codes from Local Status" feature which will allow you to set the decision even if the local_status is present.

POST /api/v2/user_identities/:user_identity_id/programs/:program_id/batch_designations

Required Parameters

Name	Type	Description	Example
designations:applicant_cas_id	string	The CAS unique identifier of the applicant.	"123456789"
designations:decision_id	integer	The unique identifier for the decision to set. If the designation is in received status and the preliminary_data_handling feature is on, the code will prevent changes to the decision code.	99

Curl Example

$ curl -n -X POST https://api.webadmit.org/api/v2/user_identities/:user_identity_id/programs/:program_id/batch_designations \
  -d '{
  "designations": [
    {
      "applicant_cas_id": "123456789",
      "decision_id": 99
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 201 Created

{
  "href": "/api/v2/user_identities/1/programs/42023191739237/batch_designations/74780",
  "batch": {
    "id": 74780,
    "status": "Queued"
  }
}

Errors

Response Example

HTTP/1.1 422 Unprocessable Entity

{
  "errors": {
    "schema": [
      "The property '#/' did not contain a required property of 'designations'"
    ]
  }
}

The request body did not match the expected request schema. Please check your parameters and try again.

{
  "errors": {
    "schema": [
      "The property '#/designations/0/applicant_cas_id' of type Fixnum did not match the following type: string"
    ]
  }
}

The request body did not match the expected value type. In that example, the applicant_cas_id property of the first object (that is, at the 0 index) must be a String, not an Integer.

Not Found

Specific error messages

HTTP/1.1 404 Not Found

When the user_identity is not found

{
  "message": "User identity '999' not found."
}

When the program is not found

{
  "message": "Program '99999999999' not found."
}

Unauthorized

Response Example

HTTP/1.1 401 Unauthorized

(Empty response body.)

---