Dartmouth API Developer Portal

Security Gift Batches API

The Security Gift Batches interface allows the caller to post security gift batches to the Dartmouth internal Security Gifts System (SG). This is a restricted service and is strictly limited to external system integrations. Application to use this service must be approved by the General Accounting office. Posted batches are monitored and audited by the General Accounting office on a daily basis.

Unauthorized use or attempted use of this service will be considered a major violation of the Dartmouth Code of Conduct/and or possibly a criminal violation and be adjucated accordingly.

Notes on usage

The entire batch of gift transactions and associated header information is passed to the api in a single POST CALL. A return code of 202 (Accepted) is given, and a payload of information about the batch, including the ID of the batch that can be used in a subsequent GET call to inquire about the status of the batch. The number of gift transactions is not limited.

The caller can check on the status of the background processing by calling the check status service, and passing in the ID of the batch resource that is returned on the initiating call to create the batch (the POST requests documented below).

COMPATIBILITY NOTE the "link" attribute returned on the post call must be followed to the status information. The format of the link may change in the future so this attribute should always be used rather than "assuming" the format of the URL.

A posting_type field is required that can have the values COMMIT or TRIAL. In TRIAL mode the batch is submitted for processing and goes through all the integrity checks. If the batch passes all these integrity checks, the batch is rolled back as if it never happened. If the posting_type is COMMIT and the batch passes all integrity checks, the batch is posted to the final application tables. In this way, you can pre-flight check the batch for errors before sending it to the Security Gift system or do testing in a production system without affecting the production data.

The postings (history) service returns previously-submitted batch postings.

Request

POST /api/advancement/gift/security_batches

Required Scope

urn:dartmouth:advancement.gift:write.transaction

Parameters

None

Body

Batch request payload (see example below)

Returns

Status Code	Description
202	The POST request has been accepted and has been handed off to the background processor
50x	The backend Oracle database is not available

Sample Request

https://api.dartmouth.edu/api/advancement/gift/security_batches

POST request with example body

{
  "posting_type": "trial",
  "source_batch_id": "12345",
  "security_gifts": [
    {
      "source_tracking_id": "1218448",
      "id_number": null,
      "netid": null,
      "first_name": "Jxxxx Bxxx",
      "last_name": "Bxxxx",
      "middle_name": "Dxxxxx",
      "email_address": "Sxxxxxxxx@xyz.net",
      "affiliation": "Dartmouth '88 P'15, P'17, P'19",
      "phone_number": "203-555-9999",
      "preferred_name": "Sxxxx  Zx Bxxxx",
      "address1": "2 Imaginary Drive",
      "address2": null,
      "address3": null,
      "city": "Greenwich",
      "state": "CT",
      "zip_suffix": null,
      "zipcode": "06830",
      "country": "USA",
      "additional_donor_first_name": "Jane",
      "additional_donor_last_name": "Doe",
      "additional_donor_middle_name": null,
      "additional_donor_affiliation": "Dartmouth '84",
      "brokerage_firm": "Merill Lynch",
      "broker_email": "xxxxxx_xxxxxxxx@gmail.com",
      "broker_name": "Merrill Lynch",
      "broker_phone": "1 (631) 361-3205",
      "contact_name": "Michael Cxxxxx / Brenda Cxxxxxxxxxxxx",
      "designation": "50% Dartmouth College Fund\r\n50% Tuck Annual Giving",
      "input_date": "2018-08-31T04:00:00Z",
      "matching_gift": "False",
      "matching_gift_details": null,
      "other_instructions": "open ended box of notes input by end user",
      "securities":
        [
          {
            "approximate_value": 1360,
            "cost_basis": 500,
            "number_of_shares": 20,
            "security_name": "Bank Of America",
            "ticker_symbol": "BAC"
          },
          {
            "approximate_value": 500,
            "cost_basis": 500,
            "number_of_shares": 55,
            "security_name": "PepsiCo",
            "ticker_symbol": "PEP"
          }
        ]
    }
  ]
}

Main Body attributes (all fields are required):

Field	Type	Description
posting_type	string	set to TRIAL for a pre-check of the batch without impacting target application, set to COMMIT to send the batch of Security Gifts to the target application. In both cases integrity checks are performed to ensure the batch is legal
source_batch_id	string	an identifier from the source system to track back to this batch of gifts
security_gifts	array	an array of one or more gift transactions as described in the next section

Security Gift attributes:

Field	Type	Description
source_tracking_id	string	an identifier from the source system to track back to this individual gift
id_number	string	(future use if donor matching ever enabled) The ID number of the donor
netid	string
first_name	string
last_name	string
middle_name	string
email_address	string
affiliation	string	Still under discussion, the original system used this as class year affiliation
phone_number	string
address1	string
address2	string
address3	string
city	string
state	string
zip_suffix	string
zipcode	string
country	string
additional_donor_first_name	string
additional_donor_last_name	string
additional_donor_middle_name	string
additional_donor_affiliation	string	Still under discussion, the original system used this as class year affiliation
brokerage_firm	string
broker_email	string
broker_phone	string
contact_name	string
designation	string
input_date	string	Date of input by the donor in ISO8601 date format
matching_gift	string	String value representing either "True" or "False"
matching_gift_details	string
other_instructions	string
securities	array	an array of securities associated with this gift as described in the next section

Securities Attributes:

Field	Type	Description
approximate_value	number	approximate value of the gift donation as entered by the donor
cost_basis	number	cost basis of the gift as entered by the donor
number_of_shares	number	number of shares of the gift as entered by the donor
security_name	string	security name of the gift as entered by the donor
ticker_symbol	string	security name of the gift as entered by the donor

Returns

Status Code	Description
202	The batch has been accepted
50x	The backend Oracle database is not available

{
    "id": "74AD4340FD5153CEE0538801120A9DDF",
    "source_batch_id": "testing",
    "status": "Processing",
    "message": null,
    "link": "https://api-dev.dartmouth.edu/api/advancement/gift/security_batches/74AD4340FD5153CEE0538801120A9DDF",
    "submit_time": "2018-08-30T19:41:39Z",
    "number_of_entries": null,
    "completion_time": null,
    "elapsed_minutes": 0.02
}

Field	Type	Description
id	string	the id you can use on subsequent requests for getting information about the status of the batch
source_batch_id	string	the id submitted in the original request to tie back to the source system
posting_type	string	the posting type of the batch
status	string	current status of the background batch processing
message	string	message giving additional information about status. This message is suitable for display to an end user
number_of_entries	number	the number of gift transactions found in the batch
link	string	the url to follow to get information about the status of the batch
submit_time	string	date/time batch submitted for backend procesing in ISO8601 format
completion_time	string	date/time batch processing completed
elapsed_minutes	number	elapsed minutes between submit_time and completion_time

Get Batch Status

This call can be used at any time to get the current status of the batch.

Request

GET /api/advancement/gift/security_batches/{id}

Required Scope

urn:dartmouth:advancement.gift:write.transaction

Parameters

Field	Type	Description
id	string	the id of the batch

Returns

Status Code	Description
200	The status of the batch is returned
404	Not found. The {id} does not reference a valid batch id

Sample Request

GET https://api.dartmouth.edu/api/advancement/gift/security_batches/74AD4340FD5153CEE0538801120A9DDF

Sample Return Body

{
    "id": "74AD4340FD5153CEE0538801120A9DDF",
    "source_batch_id": "testing",
    "status": "Commit Success",
    "posting_type": "commit",
    "message": "Batch of testing completed.",
    "link": "https://api-dev.dartmouth.edu/api/advancement/gift/security_batches/74AD4340FD5153CEE0538801120A9DDF",
    "submit_time": "2018-08-30T19:41:39Z",
    "number_of_entries": 1,
    "completion_time": "2018-08-30T19:41:44Z",
    "elapsed_minutes": 0.08
}

Get Postings History

This call can be used at any time to get status of previously-submitted batch postings.

The status field will return one of the following values:

Status	Description
Submitted	The batch has been submitted to the backend system and awaits processing
Processing	The backend system has begun processing the batch to send it to the target application
Commit Success	The batch passed all integrity checks, and was successfully committed to the target application
Trial Success	The batch passed all integrity checks, and was then rolled back
Error	An error occured during processing, check the message field for more information

Request

GET /api/advancement/gift/security_batches

Required Scope

urn:dartmouth:advancement.gift:write.transaction

Parameters

Field	Type	Description
submit_date	string	the date the batch was submitted (yyyy-mm-dd)

Returns

Status Code	Description
200	All postings that qualify based on query parameters are returned

Sample Request

GET https://api/advancement/gift/security_batches?submit_date=2018-08-30

Sample Return

[
    {
        "source_batch_id": "testing",
        "submit_time": "2018-08-30T19:41:39Z",
        "number_of_entries": 1,
        "elapsed_minutes": 0.08,
        "current_status": "Commit Success",
        "posting_type": "commit",
        "message": "Batch of testing completed.",
        "completion_time": "2018-08-30T19:41:44Z",
        "id": "74AD4340FD5153CEE0538801120A9DDF"
    },
    {
        "source_batch_id": "74",
        "submit_time": "2018-08-30T19:40:54Z",
        "number_of_entries": null,
        "elapsed_minutes": 0,
        "current_status": "Error",
        "posting_type": "commit",
        "message": "Batch  aborted with error: ORA-01722: invalid number",
        "completion_time": "2018-08-29T19:40:54Z",
        "id": "74992304145AFB8EE0538801120A94D4"
    }
]

Monitoring Endpoint

The monitoring endpoint is used to test if any gift postings have failed. It should always return a 200 status code and an empty array. If an empty array is not returned, it means a gift failed to move from the staging area to the final application destination. The monitor continues to return the array of failed entries until the data is corrected and reprocessed successfully, clearing the error condition, or the error row is deleted from the underlying control table after confirming with the Investment Office that the gift record has been entered manually.

The monitor endpoint should rarely indicate a problem if the user input from the donor page has the appropriate input controls enabled (e.g. numeric data entry or valid dates etc.)

Request

GET /api/advancement/gift/security_batches/monitor

Required Scope

urn:dartmouth:advancement.gift:write.transaction

Parameters

None

Returns

Status Code	Description
200	All postings that qualify based on query parameters are returned

Sample Request

GET https://api/advancement/gift/security_batches/monitor

Sample Return

[]