Your first REST API requests with PHP

Get started quickly with the Sage Intacct REST API. This tutorial will show you how to use PHP to authenticate with OAuth2 server, send requests to the API, and review the responses.

Prerequisites

  • You must have an active Web Services developer license, which includes a Web Services sender ID and password. If you need a developer license, contact your account manager.
  • The company to which you will be sending API requests must authorize your sender ID. They can either add your web sender ID to the Company Security tab or log in as an admin user when approving the OAuth authorization request.
  • There must be an Intacct user with the permissions required by your application. It is strongly recommended that you use a Web Services user.
  • You must register your application with the Sage App Registry and obtain a Client ID and Client Secret . You must provide a redirect (callback) URI where the user will be redirected once authorized. See the Quick start topic for more details.
  • PHP >= 7.3
  • cURL >= 7.19.4 compiled with OpenSSL and zlib
  • Server with SSL

Set up

  1. Download and extract the PHP REST API example zip file that contains these files:
    • credentials-template.php
    • IntacctRestAuth/REST-auth.php
    • CallbackAndRestCalls/REST-example-token.php
  2. Create a new PHP project for the examples in your IDE of choice (PHPStorm, NetBeans, etc.).
  3. Make sure your server is running.
  4. Deploy the project into your web server root directory.

Overview of authentication flow

Your application must be authorized by a user in order to get an access token. The access token must be included in every API request. The OAuth2 authorization code flow involves the following steps:

  1. The user clicks a link to authorize your application.
  2. The user signs in to Intacct and grants access to their data.
  3. The authentication server responds by issuing an authorization code and redirecting the user to the registered callback URI.
  4. Capture the authorization code and use it to request an access token.
  5. Receive and capture the access token which can now be used to send requests to the REST API.

Overview of implementation

This tutorial uses two PHP files that you will host on your server. The first file REST_auth.php lets a user initiate an authorization request. The second file REST-example-token.php receives the authorization code and requests an access token, then sends an API request. REST-example-token.php file is the redirect (callback) URI which must be entered in your Sage App registry as mentioned in the Prerequisites section above.

This tutorial uses the PHP cURL extension to send HTTP GET and POST requests to the API.

Obtain the access token

Store your credentials

Open the credentials-template.php file and enter your client id and client secret. Enter you callback (redirect URI) replacing "mysite.com" with your host domain. Verify the callback URI is correctly entered in the Sage App Registry.

Copy
Copied
<?php

define ("CLIENT_ID", "*****.app.sage.com");
define ("CLIENT_SECRET", "*****");
define ("CALLBACK_URL", "https://mysite.com/CallbackAndRestCalls/REST-example-token.php");

?>

Save the file as credentials.php in your root directory. Store your file securely and exclude it from your remote repository.

Send authorization request

With the server running, the IntacctRestAuth/REST_auth.php file displays a link to the authorization endpoint that a user can click to authorize your application.

  • Endpoint: https: //api.intacct.com/ia/api/v1/oauth2/authorize
  • HTTP method: GET
  • Fields:
    • response_type: code
    • client_id:
    • redirect_uri:
    • state: a random value used to validate the response

Example request:

Copy
Copied
https://api.intacct.com/ia/api/v1/oauth2/authorize?response_type=code&client_id=b5974b6c5d6f2f1edb33.app.sage.com&redirect_uri=phttps://mysite.com/rest-callback.php&state=123456

Open the IntacctRestAuth/REST_auth.php file and examine the PHP code to send the request.

Copy
Copied
<?php

require_once '../credentials.php';

// build endpoint
$base_url = 'https://api.intacct.com/ia/api/';
$version = 'v1/';
$auth_endpoint = 'oauth2/authorize';
$auth_url = $base_url.$version.$auth_endpoint;

// build url request
$url = $auth_url."?"
    ."state=123456"
    ."&response_type=code"
    ."&client_id=". CLIENT_ID
    ."&redirect_uri=". CALLBACK_URL;

?>

<a href="<?php echo $url; ?>">Authorize application</a>

From your browser, go to the URL where you placed the REST-auth.php file on your server, for example https://mysite.com/IntacctRestAuth/REST-auth.php, and click the Authorize access link to start the authorization process. The OAuth2 server responds by opening the Sage Intacct log in page.

Log in as a user with the permissions needed by your application and authorize the application to access data.

The OAuth2 server responds by redirecting the user to the registered redirect URI and including an authorization code as a query parameter in the URL.

Send access token request

Extract the authorization code from the response, then include it in a request for the access token.

  • Endpoint: https: //api.intacct.com/ia/api/v1/oauth2/token
  • HTTP method: POST
  • Fields:
    • grant type: authorization code
    • code: < code >
    • client_id
    • client_secret
    • redirect_uri
    • content_type: application/json

Open the CallbackAndRestCalls/REST-example-token.php file and examine the PHP code to send the request.

Copy
Copied
<?php

require_once '../credentials.php';

// build endpoint
$base_url = 'https://api.intacct.com/ia/api';
$version = 'v1/';
$token_endpoint = 'oauth2/token';
$token_url = $base_url.$version.$token_endpoint;

// extract code from the authorization response
$code = $_GET['code'];

// build authentication request
$curl = curl_init($token_url);
$curl_post_data = array(
    'grant_type' => 'authorization_code',
    'code'=> $code,
    'redirect_uri' => CALLBACK_URL,
    'client_id' => CLIENT_ID,
    'client_secret' => CLIENT_SECRET
);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($curl_post_data));

// send request to authenticate
$curl_response = curl_exec($curl);
if ($curl_response === false) {
    $info = curl_getinfo($curl);
    curl_close($curl);
    die('Error occurred during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);

The response contains the access token in JSON format.

Copy
Copied
// decode response and extract access tokens
$decoded = json_decode($curl_response);
$access_token = $decoded->access_token;

Send an API request

With the access token in hand, you can now use it to send API requests to access data on behalf of the authorizing user. As an example, you can query for vendor object with key 33.

  • Endpoint: https: //api.intacct.com/ia/api/v1/objects/accounts-payable/vendor/33
  • HTTP method: GET
  • Header:
    • Authorization: Bearer < access token >

Examine the PHP code to send the request:

Copy
Copied
//query for vendor key 33 in my company
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer " . $access_token
    ],
    CURLOPT_URL => $base_url.$version."objects/accounts-payable/vendor/33",
    CURLOPT_RETURNTRANSFER => true
]);

$curl_response = curl_exec($curl);
if ($curl_response === false) {
$info = curl_getinfo($curl);
curl_close($curl);
die('Error occurred during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);

The response contains the requested vendor information in JSON format.

Copy
Copied
// extract vendor data
$response_data = json_decode($curl_response);
if ($response_data->{"ia::result"}->{"ia::error"} != null) {
    echo "Error occurred: " . $response_data->{"ia::result"}->{"ia::error"}->message;
} else {
    $response_result = $response_data->{"ia::result"};
    echo nl2br("Vendor key: " . $response_result->key . "\r\n");
    echo nl2br("Vendor id: " . $response_result->id . "\r\n");
    echo nl2br("Vendor name: " . $response_result->name . "\r\n\n");
    echo nl2br("Access token: " . $access_token . "\r\n");
}

?>

Examine the response. You will see the key, id and name information for vendor with key 33.

Copy
Copied
Vendor key: 33
Vendor id: V-00019
Vendor name: Bay Area Exhibits, Inc

Use the access token to send API requests in subsequent tutorials. Sample token is shown here:

Copy
Copied
Access token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6ImI1OTc0YjZjNWQ2ZjJmMWVkYjg0LmFwcC5zYWdlLmNvbSIsImNueUlkIjoiU3RldmUgRXZlcnl0aGluZyIsImNueUtleSI6IjQ0MTEyMTI5IiwidXNlcklkIjoic3RldmUubmF5IiwidXNlcktleSI6IjY4Iiwic2Vzc2lvbklkIjoiemVvYlFNRHBfRnk3SFFJUENIUmVRLWhQWExrZEFzM3FHMERDU09GZHV4MENEd2gwWGdkZTZWeTcifQ.giY62IE-wRtN6xuM3EBI-RaHEu4HJzZKpmSnYu2uRCo