> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Developer Quick Start
> Send your first ad request in 10 minutes
## Goals of this guide
In 10 minutes:
* ✅ Find your Placement ID
* ✅ Send your first ad request
* ✅ Check the ad response
***
## Prerequisites
**What you need**:
* An A2 account (with Developer Portal access)
* curl or Postman
* A Placement ID for testing
***
## Step 1: Open the Developer Portal (1 min)
Go to the A2 Developer Portal.
```
https://{customer_id}.a2cloud.aiderx.app/developers/
```
Select the **Developer Portal** tab on the login screen. You can sign in with the same account you use for AD Manager.
***
## Step 2: Find your Placement ID (2 min)
In AD Manager, find the **Placement ID (tagid)** of the Placement where you want to serve ads.
1. Open AD Manager (`https://{customer_id}.a2cloud.aiderx.app` - same domain as the Developer Portal)
2. Click the **Placement** menu
3. Copy the **ID** of the Placement you want to test
The Placement ID is used in the ad request URL. Make sure the Placement is **active**.
***
## Step 3: Send an ad request (3 min)
Run the following curl command in your terminal.
```bash theme={null}
curl -X POST \
-H "Content-type: application/json" \
https://{customer_id}.a2cloud.aiderx.app/app/v0/ad/{tagid} \
-d '{
"version": "0.1.0",
"user": {
"id": "test_user_123"
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}
}'
```
**Parameters**:
* `{customer_id}`: Your customer ID
* `{tagid}`: Placement ID (found in AD Manager)
The ad serving API does not require authentication. The `device.ua` field is recommended and helps improve Targeting accuracy.
***
## Step 4: Check the response (2 min)
On success, you receive a JSON response like this:
```json theme={null}
{
"version": "0.1.0",
"ad": {
"id": "ad_123456",
"display": {
"w": 300,
"h": 250,
"banner": {
"img": "https://example.com/ad-image.jpg"
}
}
},
"ext": {
"message": "success",
"ad_log": "encrypted_tracking_data..."
}
}
```
**Response fields**:
* `version`: API version (e.g., `"0.1.0"`)
* `ad.id`: Ad ID
* `ad.display.w`, `ad.display.h`: Ad size
* `ad.display.banner.img`: Banner image URL (or HTML markup may be returned in `ad.display.adm`)
* `ext.message`: Response status message
* `ext.ad_log`: Encrypted tracking data (handled automatically by the SDK)
***
## Step 5: Integrate the SDK (optional, 2 min)
Installing the SDK on your website makes serving ads easier.
```html theme={null}
My Website
```
***
## Done! 🎉
You've successfully sent your first ad request!
### Next steps
View the full API documentation and detailed parameters
Advanced SDK features and customization
Send impression, click, and conversion events
Create and manage Campaigns via the API
***
## FAQ
The **ad serving API** (`/app/v0/ad/{tagid}`) can be used without authentication. The ad requests covered in this Quick Start do not require a token.
API tokens are required only for the **Campaign management API** (creating, updating, and deleting Campaigns, etc.). If you need a token, you can issue one from the Settings menu in ADM. For details, see the [token issuance guide](/development/tutorial/en/get-token).
When there is no ad, HTTP status code 204 is returned (the response body is ignored). With the SDK, a 204 is handled as a `NoBidError` and no ad is displayed. If you set the `collapse_nobid: true` option when initializing the SDK, the ad area is hidden automatically. If you call the API directly, handle no-bid based on the 204 status code (do not rely on the body).
Call the `impression_url` from the response when the ad is displayed on screen. The SDK handles this automatically.
When a user clicks the ad, redirect to the `click_url`. A2 tracks the click automatically and then sends the user to the final landing page.
By default, up to 100 requests per second are allowed. If you need a higher limit, contact support.
***
## Troubleshooting
### 401 Unauthorized
* This error occurs only with the **Campaign management API** (not the ad serving API)
* The ad serving API (`/app/v0/ad/{tagid}`) does not require authentication - the requests covered in this Quick Start never return 401
* When using the Campaign management API: check your token in ADM Settings ([token issuance guide](/development/tutorial/en/get-token))
### 404 Not Found
* Check that the Placement ID is correct
* Check that the Placement is active
### 500 Internal Server Error
* Check that the request JSON format is valid
* If the problem persists, contact support
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.