I4A API 2.0

From i4a API Wiki
Jump to navigation Jump to search

Authentication

For security purposes, i4a API 2 will only work on a secure port through HTTPS. To access any of the API functionality, you must first authenticate.

You can manage your API login and Token values by logging into your site admin and selecing 'API Settings' from the Admin menu. On this screen, you can define a username/password to use with your API. This username will NOT count against your admin seats, however it can only be used to authenticate through the API and cannot be used as a regular admin account.

Your site should already have a token defined for it, but if you wish, you can generate a new one. Please be aware that any changes to these values will require that any existing code that uses the i4a API must be updated with your changed values.


Authentication Endpoint

POST /i4a/api2/authenticate/


Parameters

username

form | required

See API Settings page on how to obtain the value.
password

form | required

See API Settings page on how to obtain the value.
token

form | required

See API Settings page on how to obtain the value.


Example: 

curl --location --request POST 'https://<yourdomain.com>/i4a/api2/authenticate/' \
--form 'username="XXXXXXXX"' \
--form 'password="XXXXXXXX"' \
--form 'token="XXXXXX-XXXX-XXXXX-XXXXXXXXXXX"'

Response: 

{
    "expiration": "{ts '2022-10-25 16:03:47'}",
    "success": true,
    "authKey": "XXXXXX-XXXX-XXXXX-XXXXXXXXXXX",
    "error": ""
}

Retrieving Data

Once you have successfully obtained the authKey, you can then access a few different read-only endpoints. Note: Your authKey will expire after 4 hours.


Contacts Endpoint

Retrieve contact/member data from the database. 

POST /i4a/api2/contacts/


Parameters

authKey

header | required

The authKey you received during authentication.
Content-Type

header | optional

Set this to application/x-www-form-urlencoded or multipart/form-data.
filter

form | optional

This is the query filter.

Basic usage: lastName:Doe - this will search for contacts where lastName = 'Doe'. Note: the colons separate column name and filter value. If more than one filter is needed, please use commas: lastName:Doe,email:test@domain.com. This will search for contacts where lastName = 'Doe' AND email = 'test@domain.com'.

Advanced usage: You can write your own query filter as such: city ='Chicago' OR email LIKE '%i4a%' Note: do not include the keyword 'WHERE'. You may use other query operators (= > < >= <= <> BETWEEN LIKE IN). Date values to query against must be in the format 'yyyy-MM-dd'.

filterOperator

form | optional

This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
pageSize

form | optional

The number of results to return. Maximum is 100 (default).
page

form | optional

The page number, starting at 1 (default). This is useful when your query returns more records than the 'pageSize' allows.


Example (by ContactID): 

curl --location --request POST 'https://yourdomain.com/i4a/api2/contacts/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: multipart/form-data' \
--form 'filter="contactID:693681"'

Response: 

{
    "success": true,
    "data": [
        {
            "zip": "12345",
            "corpexpiration": "",
            "c_user_memo": "",
            "firstname": "John",
            "customid": "649",
            "email": "john@site.com",
            "contactid": "693681",
            "corptype": "",
            "country": "US",
            "lastname": "Doe",
            "iscorp": 0,
            "corpjoindate": "",
            "id": "693681",
            "middle": "",
            "c_user_photo": "",
            "orgid": "150514",
            "suffix": "",
            "creationdate": "2021-11-08 15:31:50.0",
            "modifiedby": "692686",
            "c_user_gender": "",
            "modifieddate": "2021-11-08 15:31:50.0",
            "isemail": 0,
            "c_user_graduationdate": "",
            "datedropped": "",
            "isactive": 1,
            "daterenewed": "",
            "company": "",
            "region": "",
            "c_user_birthday": "",
            "prefix": "",
            "review": 0,
            "c_user_certified": "",
            "ccmail": "",
            "c_user_uploadbio": "",
            "phone": "555-1234",
            "state": "OH",
            "paidthru": "",
            "c_user_end_market": "",
            "primarycontact": "693681",
            "url": "",
            "member_status": "",
            "address1": "555 Street",
            "isdirectory": 1,
            "address3": "",
            "address2": "",
            "datejoined": "",
            "c_user_occupation": "",
            "addid": "140467",
            "groupid": "693681",
            "city": "Cincinnati",
            "isprimary": 1,
            "informalname": "",
            "title": "",
            "fax": "",
            "c_user_resume": ""
        }
    ],
    "error": "",
    "page": 1,
    "pagesize": "100"
}


Example (by lastName): 

curl --location --request POST 'https://yourdomain.com/i4a/api2/contacts/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: multipart/form-data' \
--form 'filter="lastName:Doe"'

Response: 

{
    "success": true,
    "data": [
        {
            "zip": "12345",
            "corpexpiration": "",
            "c_user_memo": "",
            "firstname": "John",
            "customid": "649",
            "email": "john@site.com",
            "contactid": "693681",
            "corptype": "",
            "country": "US",
            "lastname": "Doe",
            "iscorp": 0,
            "corpjoindate": "",
            "id": "693681",
            "middle": "",
            "c_user_photo": "",
            "orgid": "150514",
            "suffix": "",
            "creationdate": "2021-11-08 15:31:50.0",
            "modifiedby": "692686",
            "c_user_gender": "",
            "modifieddate": "2021-11-08 15:31:50.0",
            "isemail": 0,
            "c_user_graduationdate": "",
            "datedropped": "",
            "isactive": 1,
            "daterenewed": "",
            "company": "",
            "region": "",
            "c_user_birthday": "",
            "prefix": "",
            "review": 0,
            "c_user_certified": "",
            "ccmail": "",
            "c_user_uploadbio": "",
            "phone": "555-1234",
            "state": "OH",
            "paidthru": "",
            "c_user_end_market": "",
            "primarycontact": "693681",
            "url": "",
            "member_status": "",
            "address1": "555 Street",
            "isdirectory": 1,
            "address3": "",
            "address2": "",
            "datejoined": "",
            "c_user_occupation": "",
            "addid": "140467",
            "groupid": "693681",
            "city": "Cincinnati",
            "isprimary": 1,
            "informalname": "",
            "title": "",
            "fax": "",
            "c_user_resume": ""
        }
    ],
    "error": "",
    "page": 1,
    "pagesize": "100"
}

Views Endpoint

Retrieve data from any view in the database. 

POST /i4a/api2/views/

Parameters

authKey

header | required

The authKey you received during authentication.
Content-Type

header | optional

Set this to application/x-www-form-urlencoded or multipart/form-data.
view

form | required

This is the name of the view for the query.
filter

form | optional

This is the query filter.

Basic usage: lastName:Doe - this will search for contacts where lastName = 'Doe'. Note: the colons separate column name and filter value. If more than one filter is needed, please use commas: lastName:Doe,email:test@domain.com. This will search for contacts where lastName = 'Doe' AND email = 'test@domain.com'.

Advanced usage: You can write your own query filter as such: city ='Chicago' OR email LIKE '%i4a%' Note: do not include the keyword 'WHERE'. You may use other query operators (= > < >= <= <> BETWEEN LIKE IN). Date values to query against must be in the format 'yyyy-MM-dd'.

filterOperator

form | optional

This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
pageSize

form | optional

The number of results to return. Maximum is 100 (default).
page

form | optional

The page number, starting at 1 (default). This is useful when your query returns more records than the 'pageSize' allows.


Example: 

curl --location --request POST 'https://yourdomain.com/i4a/api2/views/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: multipart/form-data' \
--form 'filter="TYPE IN ('\''Cash'\'', '\''Income'\'') AND title LIKE '\''%Membership%'\''"' \
--form 'view="chart of accounts"'


Response: 

{
    "success": true,
    "data": [
        {
            "title": "Membership Dues",
            "id": "8",
            "gl_number": "6000",
            "description": "Membership Dues General",
            "type": "Income"
        },
        {
            "title": "Membership Extra Dues",
            "id": "32",
            "gl_number": "7988-66",
            "description": "Membership Extra Dues",
            "type": "Income"
        }
    ],
    "error": "",
    "page": 1,
    "pagesize": "100"
}

Membership Endpoint

POST /i4a/api2/membership/


Parameters

authKey

header | required

The authKey you received during authentication.
Content-Type

header | optional

Set this to application/x-www-form-urlencoded or multipart/form-data.
contactID

form | optional

The contact ID of a given contact/member. Required if email is not provided.
email

form | optional

The email address of a given contact/member. Required if contactID is not provided.


Examples: 

url --location --request POST 'https://yourdomain.com/i4a/api2/membership/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--form 'contactID="12345"'

url --location --request POST 'https://yourdomain.com/i4a/api2/membership/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: multipart/form-data' \
--form 'email="email@domain.com"'

Responses: 

{
    "success": true,
    "data": {
        "memberstatus": "current",
        "ismember": true,
        "expiration": "2024-12-31",
        "graceperiod": "60",
        "membertype": "Individual"
    },
    "error": ""
}

{
    "success": true,
    "data": {
        "memberstatus": "expired",
        "ismember": true,
        "expiration": "2022-12-31",
        "graceperiod": "0",
        "membertype": "Regular"
    },
    "error": ""
}

{
    "success": true,
    "data": {
        "memberstatus": "non-member",
        "ismember": false,
        "expiration": "",
        "graceperiod": "",
        "membertype": ""
    },
    "error": ""
}
Retrieved from "https://api.i4a.com/index.php?title=I4A_API_2.0&oldid=206"