API Integration (AIE)

Onboarding Progress

Step 1: Getting Started ✓
Step 2: API Integration (AIE)
Step 3: Data Qualification (DQE)
Step 4: Production Launch

Step 2: Integrate with the API

The API Integration Environment (AIE) is where you will test your platform's connection with the Business API using test data. This phase typically takes two to three weeks to complete.

important

Although the data submitted to AIE is not published externally, you should only send test data to this environment.

API Integration Sequence of Tasks

1. Request API Access.
2. Review Testing and API Usage Expectations.
3. Create a Service Account.
4. Collect Integration Parameters.
5. Complete the AIE Exit Criteria.
6. Request API Integration Verification.
7. View API Integration Progress Reports.
8. Complete the API Integration Exit Process.

Integration Requirements

• You must support three separate server environments: AIE, DQE, and Production.
• You will need a Box account to retrieve onboarding progress reports from a Box folder created by Apple Business.
• Send only production data to DQE. The AIE accepts test data.

Testing and API Usage Expectations

General Testing Expectations:

• Integrate with your platform.
• Poll the Get Notifications API for state changes.
• Check submission states, correct errors, and resubmit.
• Complete all AIE Exit Criteria.

API Usage Expectations:

• Avoid LOCATION_MARKED_DELETED errors, which are caused by deleting and then recreating a location.
• Avoid LOCATION_ALREADY_EXISTS errors, which are caused by submitting duplicate location data.
• Limit HTTP 4xx errors to less than one per hour.
• Reuse tokens until they expire; do not retrieve a new token for each request.

Request API Integration Verification

Once you have completed the AIE exit criteria, you can request verification of your API integration.

1. Navigate to Organization > Organization Name > API > API Integration ().
2. Select Verify API Integration > Send.
3. You can optionally confirm receipt via the embedded alert in the API Access pane.

View API Integration Progress Reports

API integration progress reports list the status of your API integration. These reports are generated daily and posted to your API integration Box folder until you pass all criteria.

1. You will receive an email from Apple Business with the pass/fail results of your API integration.

• If you pass, you can proceed to Step 3: Submit All Your Data.
• If you do not pass, continue to the next step.

2. Sign in to the Apple Business portal and select Organization > Organization Name > API.
3. In the API Integration pane, a message will indicate that your API integration was not approved. Select View Details.
4. Access the reports in your Box folder.

Access Box Folder Reports

In the "Not Approved" dialog, select the Box folder link to view your progress reports.

tip

If the Box folder does not open, sign in to your organization's Box account first, then select the Box folder link again.

API Integration Exit Process

1. Correct any "Fail" items listed in the API integration progress report.
2. Repeat the Request API Integration Verification process.
3. Repeat the process of viewing the API Integration progress reports.

• Progress reports are automatically updated daily. Use the Box folder link to view the latest report and apply corrections. You can also select the report button to refresh the progress report at any time.

4. Repeat steps 1 through 3 until your API integration passes.

• When your API integration passes, you will receive an email from Apple Business announcing that you are approved to start data qualification.

5. Proceed to Step 3: Submit All Your Data.