== 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.

=== Authentication Endpoint ===
<syntaxhighlight lang="html">
POST /i4a/api2/authenticate/
</syntaxhighlight>

'''Parameters'''
{| class="wikitable" style="width: 100%;"
|style="width: 20%;"|<code>username</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|-
| <code>password</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|-
| <code>token</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|}

'''Example''':

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

'''Response:'''
<syntaxhighlight lang="json">
{
"expiration": "{ts '2022-10-25 16:03:47'}",
"success": true,
"authKey": "XXXXXX-XXXX-XXXXX-XXXXXXXXXXX",
"error": ""
}
</syntaxhighlight>

== 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.

<syntaxhighlight lang="html">
POST /i4a/api2/contacts/
</syntaxhighlight>

'''Parameters'''
{| class="wikitable" style="width: 100%;"
|style="width: 20%;"|<code>authKey</code>
header | required
| The authKey you received during authentication.
|-
| <code>Content-Type</code>
header | required
| Set this to <code>application/json</code>.
|-
| <code>filter</code>
form | optional
| 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>
form | optional
| This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
|-
| <code>pageSize</code>
form | optional
| The number of results to return. Maximum is 100 (default).
|-
| <code>page</code>
form | optional
| 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/contacts/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--form 'filter="lastName:Doe"'
</syntaxhighlight>

'''Response:'''
<syntaxhighlight lang="json">
{
"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"
}
</syntaxhighlight>

=== 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>
header | required
| The authKey you received during authentication.
|-
| <code>Content-Type</code>
header | required
| Set this to <code>application/json</code>.
|-
| <code>view</code>
form | required
| This is the name of the view for the query.
|-
| <code>filter</code>
form | optional
| 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>
form | optional
| This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
|-
| <code>pageSize</code>
form | optional
| The number of results to return. Maximum is 100 (default).
|-
| <code>page</code>
form | optional
| 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: application/json' \
--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>contactID</code>
form | required
| The contact ID of a given user/member.
|}

'''Example''':

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

'''Response:'''
<syntaxhighlight lang="json">
{
"success": true,
"data": {
"memberstatus": "non-member",
"ismember": false
},
"error": ""
}
</syntaxhighlight>

[[Category:API]]

I4A API 2.0

2022-10-28T16:12:04Z

Felix2:

== 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.

=== Authentication Endpoint ===
<syntaxhighlight lang="html">
POST /i4a/api2/authenticate/
</syntaxhighlight>

'''Parameters'''
{| class="wikitable" style="width: 100%;"
|style="width: 20%;"|<code>username</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|-
| <code>password</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|-
| <code>token</code>
form | required
| See [[API Settings]] page on how to obtain the value.
|}

'''Example''':

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

'''Response:'''
<syntaxhighlight lang="json">
{
"expiration": "{ts '2022-10-25 16:03:47'}",
"success": true,
"authKey": "XXXXXX-XXXX-XXXXX-XXXXXXXXXXX",
"error": ""
}
</syntaxhighlight>

== 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.

<syntaxhighlight lang="html">
POST /i4a/api2/contacts/
</syntaxhighlight>

'''Parameters'''
{| class="wikitable" style="width: 100%;"
|style="width: 20%;"|<code>authKey</code>
header | required
| The authKey you received during authentication.
|-
| <code>Content-Type</code>
header | required
| Set this to <code>application/json</code>.
|-
| <code>filter</code>
form | optional
| 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>
form | optional
| This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
|-
| <code>pageSize</code>
form | optional
| The number of results to return. Maximum is 100 (default).
|-
| <code>page</code>
form | optional
| 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/contacts/' \
--header 'authKey: XXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--form 'filter="lastName:Doe"'
</syntaxhighlight>

'''Response:'''
<syntaxhighlight lang="json">
{
"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"
}
</syntaxhighlight>

=== 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>
header | required
| The authKey you received during authentication.
|-
| <code>Content-Type</code>
header | required
| Set this to <code>application/json</code>.
|-
| <code>view</code>
form | required
| This is the name of the view for the query.
|-
| <code>filter</code>
form | optional
| 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>
form | optional
| This can be either 'OR' or 'AND' (default). Only applicable when filter is used with colons.
|-
| <code>pageSize</code>
form | optional
| The number of results to return. Maximum is 100 (default).
|-
| <code>page</code>
form | optional
| 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: application/json' \
--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>contactID</code>
form | required
| The contact ID of a given user/member.
|}

'''Example''':

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

'''Response:'''
<syntaxhighlight lang="json">
{
"success": true,
"data": {
"memberstatus": "non-member",
"ismember": false
},
"error": ""
}
</syntaxhighlight>

[[Category:API]]

2022-10-26T17:00:36Z

Felix2: /* Authentication Endpoint */

I4A API 2.0

2022-10-26T16:59:36Z

Felix2: /* Security */