> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deeplink.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Track install

> Record an app install and receive attribution (referrer or UTM)

Use this endpoint when your app is opened after install (or on first launch) to record the install and get attribution. The backend can attribute the install to a DeepLink click (e.g. by **Android install referrer** or by **matching a recent iOS click** by IP/time). No authentication is required for this public tracking endpoint.

## Endpoint

```
POST /api/v1/track/install
```

Replace the base URL with your API host (e.g. `https://api.deeplink.invyto.in` or your self-hosted URL).

## Request

Send a JSON body with the following optional fields. The server will use request IP and `User-Agent` when values are omitted.

| Field         | Type   | Required | Description                                                                                                     |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `platform`    | string | No       | `"android"`, `"ios"`, or `"web"`. Inferred from User-Agent if not set.                                          |
| `referrer`    | string | No       | **Android**: install referrer string (e.g. from Install Referrer API). Used to attribute the install to a link. |
| `linkId`      | string | No       | DeepLink link ID if you already know which link to attribute (e.g. from deferred deep link flow).               |
| `model`       | string | No       | Device model.                                                                                                   |
| `packageName` | string | No       | **Android**: app package name.                                                                                  |
| `browser`     | string | No       | Browser name. Defaults to parsed User-Agent.                                                                    |
| `userAgent`   | string | No       | Full User-Agent. Defaults to request header.                                                                    |
| `OSVersion`   | string | No       | OS version. Defaults to parsed User-Agent.                                                                      |
| `ipAddress`   | string | No       | Client IP. Defaults to request IP.                                                                              |
| `country`     | string | No       | Country.                                                                                                        |
| `state`       | string | No       | State/region.                                                                                                   |
| `city`        | string | No       | City.                                                                                                           |
| `deviceId`    | string | No       | Optional device identifier. Defaults to `model`, `referrer`, or a fallback.                                     |

### Example request

```bash theme={null}
curl -X POST 'https://api.deeplink.invyto.in/api/v1/track/install' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "android",
    "referrer": "utm_source=campaign&utm_campaign=summer",
    "packageName": "com.yourapp.client",
    "OSVersion": "14"
  }'
```

```json theme={null}
{
  "platform": "android",
  "referrer": "utm_source=campaign&utm_campaign=summer",
  "packageName": "com.yourapp.client",
  "OSVersion": "14"
}
```

## Response

* **200** — Install recorded. Body format depends on attribution:

  * **Organic** (no link attributed):
    ```json theme={null}
    { "status": "organic" }
    ```
  * **Android with referrer** (referrer string returned for your use):
    ```json theme={null}
    { "method": "referrer", "data": "utm_source=..." }
    ```
  * **iOS (or when linkId is used)** — UTM from the matched click:
    ```json theme={null}
    {
      "utm_source": "email",
      "utm_medium": "newsletter",
      "utm_campaign": "summer"
    }
    ```
  * If you sent `linkId`, the backend associates the install with that link; the response may still include UTM or a simple success payload depending on implementation.

* **500** — Server error. Response body: `{ "error": "Internal Server Error" }`.

## Attribution behavior

* **Android** — If you send `referrer`, the backend can associate the install with a link that generated that referrer. The response may echo the referrer or return UTM derived from it.
* **iOS** — There is no install referrer. The backend typically matches the install to a **recent click** (e.g. same IP within a time window) and returns that click’s UTM in the response.
* **linkId** — If your app already knows the link (e.g. from deferred deep link data), sending `linkId` ensures the install is attributed to that link.

## Example: Flutter/Dart

```dart theme={null}
final response = await http.post(
  Uri.parse('https://api.deeplink.invyto.in/api/v1/track/install'),
  headers: {'Content-Type': 'application/json'},
  body: jsonEncode({
    'platform': 'android', // or 'ios'
    'referrer': referrer,   // from Install Referrer on Android; omit on iOS
    'packageName': 'com.yourapp.client',
    'OSVersion': await getOsVersion(),
  }),
);
final attribution = jsonDecode(response.body);
// Use attribution.utm_source, attribution.utm_campaign, etc. for routing or analytics.
```

## See also

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Use the Flutter SDK to call Track Install automatically.
  </Card>

  <Card title="Flutter SDK" icon="mobile" href="/sdk/installation">
    Install and init the SDK for install attribution.
  </Card>
</CardGroup>