External Gift API Reference

Overview

This document provides an overview of the External Gift API endpoint for importing single gifts into iMIS.

The External Gift API endpoint is a REST/JSON-based API endpoint.

Authentication

Authentication uses a pre-shared, static Bearer token.

Pass the token as a static Authorization Bearer token:

^{Authorization: Bearer TOKEN_VALUE_HERE}

Rate Limits

While there are no explicit rate limits in place on the API, please be aware that excessive calls can disrupt the client's server or environment.

As a general rule of thumb, it takes iMIS between 2 to 5 seconds to fully process a gift.

Therefore, avoid multiple concurrent requests. Process each request in sequence, not in parallel. If possible, implement a queue system to spread out requests.

Concepts / Terminology

• Transaction ID – A generic numeric code value, not to exceed 16 characters, which uniquely identifies this transaction.

  • Note that this Transaction ID is shared amongst multiple potential third parties, so it is a best practice to prefix your transaction IDs or ensure they are otherwise globally unique.

• Financial Account ID – This is an arbitrary ID that is used by CSiDonate to hold various financial settings and preferences.

  • CSI will provide this value to you on behalf of the client. Do not use any other value than the one provided. Do not use any value equal to or less than zero (0).

• iMIS ID – A 10-character alphanumeric (but usually limited to numbers) value which uniquely identifies any contact record in iMIS (individual or company/group/chapter).

• Distribution – Generally speaking, this is a way to identify a fund in iMIS. Distributions, in addition to pointing to funds, can also optionally contain a default appeal or campaign code. Conceptually, a distribution is synonymous with a fund.

• Campaign – A code value indicating which fundraising campaign this donation should be tied to.

• Appeal – A code value indicating which fundraising appeal this donation should be tied to.

Endpoints

See the Models section below for documentation regarding request and response bodies.

POST /api/v1/integrations/importGift

Inserts a gift to be imported at a later date.

Request Body: A single Gift Import Request JSON object.

Successful Response: 202 Accepted

GET /api/v1/integrations/distributions

Retrieves a list of valid distribution codes and descriptions.

Returns: A JSON array of Distribution objects.

Successful Response: 200 OK

GET /api/v1/integrations/appeals

Retrieves a list of valid appeal codes and descriptions.

Returns: A JSON array of Appeal objects.

Successful Response: 200 OK

GET /api/v1/integrations/campaigns

Retrieves a list of valid campaign codes and descriptions.

Returns: A JSON array of Campaign objects.

Successful Response: 200 OK

Responses

200 OK

A 200 OK indicates that the request was successful and, in some cases, the request body contains the requested information as a JSON response.

202 Accepted

A 202 Accepted response status indicates that your request was successfully received and recorded into the database for later processing.

400 Bad Request

A 400 Bad Request response status indicates that there was a preliminary validation error with the request body.

See the Message property on the response JSON object for a description of the validation error. Below are some examples of validation errors that can occur.

401 Unauthorized

A 401 Unauthorized response status indicates that the Bearer token was missing or incorrect from the request.

^{{"Message":"Authorization has been denied for this request."}}

405 Method Not Allowed

A 405 Method Not Allowed response is returned when the HTTP verb is not supported on the target URL. Typically this indicates a GET where a POST was required or vice versa.

^{{"Message":"The requested resource does not support http method 'POST'."}}

500 Internal Server Error

This occurs if there was an error inserting the gift request into the database.

The request should be attempted again, or if the error persists, contact CSI for assistance.

Models

Gift Import Request

 – Required
 – Conditionally required depending on other fields

Important Note

Property names are case-sensitive.

Business Rules

Contact Information

CSiDonate must match a gift to a contact record in iMIS.

If we are not able to find a match, or an explicit ID is not provided, CSiDonate will then create a new contact record in iMIS for this gift.

Therefore, you MUST provide any one of the following set of data:

• iMIS ID

• --OR--

• First Name and Last Name

• --OR--

• Company Name (only used if this is a corporate gift / company check)

Transaction ID

The Transaction ID must be globally unique, that is, it must be unique to any other external financial system that may interact with iMIS.

It is best practice to use a randomly generated alphanumeric string for this value, with length of at least 8. This ensures sufficient random entropy to avoid a collision.

Avoid using auto-incrementing int values for this field, unless you are able to prefix the number with a unique identifier for your system.

Distribution / Fund

CSiDonate will use the provided Distribution Code as-is when writing the gift.

However, it is also possible to set up a mapping, for cases where the distribution code is otherwise not able to be sent over.

In this special case, the Campaign Code can be set up to be mapped to a desired Distribution Code within iMIS, without explicitly knowing the distribution code itself. When this feature is used, the Campaign Code is always blank when sent to iMIS – it is "consumed" during the mapping, and otherwise not able to be used.

See the Gen Tables page for information on how to set up the mapping.

The presence of the gen table determines if this feature is activated or not.

Example Gift Import Request JSON

{
   "imisId": "",
   "amount": 12.34,
   "financialAccountId": 6,
   "nameTitle": "Mr.",
   "firstName": "Bob",
   "middleName": "A.",
   "maidenName": "Test",
   "lastName": "McTester",
   "nameSuffix": "T.S.T.R.",
   "company": "",
   "address": "123 Main Sr",
   "city": "Testertown",
   "state": "NY",
   "zipCode": "10001",
   "emailAddress": "bmctester@example.org",
   "phone": "(555) 555-1234",
   "notes": "",
   "distribution": "BMOC",
   "campaignCode": "",
   "appealCode": "IL",
   "receivedDate": "2018-12-01T08:45:32.847",
   "transactionId": "900000004"
}

Distributions

Example Distribution Response

[
  {
    "Title": "Alpha",
    "Code": "ALPHA",
    "AppealCode": "",
    "CampaignCode": ""
  },
  {
    "Title": "Alpha Gamma",
    "Code": "ALGA",
    "AppealCode": "",
    "CampaignCode": ""
  },
  ...
  {
    "Title": "Zeta Beta",
    "Code": "ZEBE",
    "AppealCode": "",
    "CampaignCode": ""
  }
}

Appeals

Example Appeal Response

[
  {
    "Code": "100000",
    "Description": "100000 - Alpha"
  },
  {
    "Code": "100004",
    "Description": "100001 - Beta"
  },
  {
    "Code": "100003",
    "Description": "100002 - Delta"
  },
  ...
]

Campaigns

Example Campaign Response

[
  {
    "Code": "5K_RUN_WALK",
    "Description": "5K_RUN_WALK - 5K Run/Walk"
  },
  {
    "Code": "SAFE",
    "Description": "SAFE - A Safe Place"
  },
  {
    "Code": "ACTS",
    "Description": "ACTS - Acts of Kindness Fund"
  },
  {
    "Code": "AARS",
    "Description": "AARS - Area Alumnae Recognition Scholarship"
  },
  ...
]