I4A API 2.0: Difference between revisions

Latest revision as of 16:00, 27 October 2023

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: multipart/form-data' \
--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": ""
}

Resources

Postman is a great tool to test and debug API calls.

I4A API 2.0: Difference between revisions

Latest revision as of 16:00, 27 October 2023

Contents

Authentication

Authentication Endpoint

Retrieving Data

Contacts Endpoint

Views Endpoint

Membership Endpoint

Resources

Navigation menu

@@ Line 1: / Line 1: @@
 ==  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. Information is available on the [[API Settings]] page on how to obtain the values needed to authenticate and update them, if need be.
+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 ===
 <syntaxhighlight lang="html">
-'''POST''' /i4a/api2/authenticate/
+POST /i4a/api2/authenticate/
 </syntaxhighlight>
@@ Line 29: / Line 33: @@
 <syntaxhighlight lang="bash">
-curl --location --request POST 'https://<yourdomain.com>/i4a/api2/authenticate' \
+curl --location --request POST 'https://<yourdomain.com>/i4a/api2/authenticate/' \
 --form 'username="XXXXXXXX"' \
 --form 'password="XXXXXXXX"' \
@@ Line 50: / Line 54: @@
 === Contacts Endpoint ===
+Retrieve contact/member data from the database.
 <syntaxhighlight lang="html">
 POST /i4a/api2/contacts/
@@ Line 62: / Line 68: @@
 |-
 | <code>Content-Type</code>
-<small>header | required</small>
+<small>header | optional</small>
-| Set this to <code>application/json</code>.
+| Set this to <code>application/x-www-form-urlencoded</code> or <code>multipart/form-data</code>.
 |-
 | <code>filter</code>
@@ Line 88: / Line 94: @@
+'''Example (by ContactID)''':
-'''Example''':
 <syntaxhighlight lang="bash">
 curl --location --request POST 'https://yourdomain.com/i4a/api2/contacts/' \
 --header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
---header 'Content-Type: application/json' \
+--header 'Content-Type: multipart/form-data' \
---form 'filter="lastName:Doe"'
+--form 'filter="contactID:693681"'
 </syntaxhighlight>
@@ Line 105: / Line 110: @@
          {
              "zip": "12345",
-             "corpexpiration": "2034-11-01 01:00:00.0",
+             "corpexpiration": "",
              "c_user_memo": "",
-             "firstname": "Tim",
+             "firstname": "John",
-             "customid": "645",
+             "customid": "649",
-             "email": "tim@test.com",
+             "email": "john@site.com",
-             "contactid": "693295",
+             "contactid": "693681",
-             "corptype": "Regular",
+             "corptype": "",
              "country": "US",
-            "c_user_test_default_no": false,
              "lastname": "Doe",
-             "iscorp": 1,
+             "iscorp": 0,
-             "corpjoindate": "2017-09-12 01:00:00.0",
+             "corpjoindate": "",
-             "id": "693295",
+             "id": "693681",
-             "middle": "J.",
+             "middle": "",
-            "c_user_pets": "cats,monkeys",
              "c_user_photo": "",
-             "orgid": "115893",
+             "orgid": "150514",
              "suffix": "",
-             "creationdate": "2018-04-16 12:18:30.0",
+             "creationdate": "2021-11-08 15:31:50.0",
-             "modifiedby": "693295",
+             "modifiedby": "692686",
              "c_user_gender": "",
-             "modifieddate": "2021-12-08 13:22:47.0",
+             "modifieddate": "2021-11-08 15:31:50.0",
              "isemail": 0,
              "c_user_graduationdate": "",
              "datedropped": "",
              "isactive": 1,
-             "daterenewed": "2022-12-09 01:00:00.0",
+             "daterenewed": "",
-             "company": "HQC Inc.",
+             "company": "",
              "region": "",
              "c_user_birthday": "",
-             "prefix": "Mr.",
+             "prefix": "",
              "review": 0,
              "c_user_certified": "",
              "ccmail": "",
              "c_user_uploadbio": "",
-             "phone": "5551234",
+             "phone": "555-1234",
              "state": "OH",
-             "paidthru": "2034-11-01 01:00:00.0",
+             "paidthru": "",
              "c_user_end_market": "",
-             "primarycontact": "693295",
+             "primarycontact": "693681",
              "url": "",
              "member_status": "",
-             "address1": "123 Happy Lane",
+             "address1": "555 Street",
              "isdirectory": 1,
              "address3": "",
              "address2": "",
-             "datejoined": "2007-07-23 05:00:00.0",
+             "datejoined": "",
              "c_user_occupation": "",
-             "addid": "140462",
+             "addid": "140467",
-             "groupid": 0,
+             "groupid": "693681",
-             "city": "Chicago",
+             "city": "Cincinnati",
              "isprimary": 1,
              "informalname": "",
@@ Line 161: / Line 164: @@
              "fax": "",
              "c_user_resume": ""
-         },
+         }
+    ],
+    "error": "",
+    "page": 1,
+    "pagesize": "100"
+}
+</syntaxhighlight>
+'''Example (by lastName)''':
+<syntaxhighlight lang="bash">
+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"'
+</syntaxhighlight>
+'''Response:'''
+<syntaxhighlight lang="json">
+{
+    "success": true,
+    "data": [
          {
-             "zip": "",
+             "zip": "12345",
              "corpexpiration": "",
              "c_user_memo": "",
@@ Line 227: / Line 253: @@
 === Views Endpoint ===
+Retrieve data from any view in the database.
 <syntaxhighlight lang="html">
 POST /i4a/api2/views/
 </syntaxhighlight>
+'''Parameters'''
+{| class="wikitable" style="width: 100%;"
+|style="width: 20%;"|<code>authKey</code>
+<small>header | required</small>
+| The authKey you received during authentication.
+|-
+| <code>Content-Type</code>
+<small>header | optional</small>
+| Set this to <code>application/x-www-form-urlencoded</code> or <code>multipart/form-data</code>.
+|-
+| <code>view</code>
+<small>form | required</small>
+| This is the name of the view for the query.
+|-
+| <code>filter</code>
+<small>form | optional</small>
+| This is the query filter.
+'''Basic usage:''' <code>lastName:Doe</code> - 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:
+<code>lastName:Doe,email:test@domain.com</code>. This will search for contacts where lastName = 'Doe' AND email = 'test@domain.com'.
+'''Advanced usage:''' You can write your own query filter as such: <code>city ='Chicago' OR email LIKE '%i4a%'</code> '''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'.
+|-
+| <code>filterOperator</code>
+<small>form | optional</small>
+| This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
+|-
+| <code>pageSize</code>
+<small>form | optional</small>
+| The number of results to return. Maximum is 100 (default).
+|-
+| <code>page</code>
+<small>form | optional</small>
+| The page number, starting at 1 (default). This is useful when your query returns more records than the 'pageSize' allows.
+|}
+'''Example''':
+<syntaxhighlight lang="bash">
+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"'
+</syntaxhighlight>
+'''Response:'''
+<syntaxhighlight lang="json">
+{
+    "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"
+}
+</syntaxhighlight>
+=== Membership Endpoint ===
+<syntaxhighlight lang="html">
+POST /i4a/api2/membership/
+</syntaxhighlight>
+'''Parameters'''
+{| class="wikitable" style="width: 100%;"
+|style="width: 20%;"|<code>authKey</code>
+<small>header | required</small>
+| The authKey you received during authentication.
+|-
+| <code>Content-Type</code>
+<small>header | optional</small>
+| Set this to <code>application/x-www-form-urlencoded</code> or <code>multipart/form-data</code>.
+|-
+| <code>contactID</code>
+<small>form | optional</small>
+| The contact ID of a given contact/member. Required if email is not provided.
+|-
+| <code>email</code>
+<small>form | optional</small>
+| The email address of a given contact/member. Required if contactID is not provided.
+|}
+'''Examples''':
+<syntaxhighlight lang="bash">
+url --location --request POST 'https://yourdomain.com/i4a/api2/membership/' \
+--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
+--header 'Content-Type: multipart/form-data' \
+--form 'contactID="12345"'
+</syntaxhighlight>
+<syntaxhighlight lang="bash">
+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"'
+</syntaxhighlight>
+'''Responses:'''
+<syntaxhighlight lang="json">
+{
+    "success": true,
+    "data": {
+        "memberstatus": "current",
+        "ismember": true,
+        "expiration": "2024-12-31",
+        "graceperiod": "60",
+        "membertype": "Individual"
+    },
+    "error": ""
+}
+</syntaxhighlight>
+<syntaxhighlight lang="json">
+{
+    "success": true,
+    "data": {
+        "memberstatus": "expired",
+        "ismember": true,
+        "expiration": "2022-12-31",
+        "graceperiod": "0",
+        "membertype": "Regular"
+    },
+    "error": ""
+}
+</syntaxhighlight>
+<syntaxhighlight lang="json">
+{
+    "success": true,
+    "data": {
+        "memberstatus": "non-member",
+        "ismember": false,
+        "expiration": "",
+        "graceperiod": "",
+        "membertype": ""
+    },
+    "error": ""
+}
+</syntaxhighlight>
+== Resources ==
+* [https://www.postman.com/ Postman] is a great tool to test and debug API calls.
+[[Category:API]]