# Partner External Id

## About

The primary use of the `partnerExternalId` is to allow clients to track and retrieve information about an entity created via the Monta API, even if the request’s response was lost, failed, or unprocessed due to unforeseen circumstances.

With `partnerExternalId` set the API integration can be improved in the following ways:

* **Reliability**: Disruptions may be handled in a better way, clients can implement checks to ensure the actual state of their data.
* **Consistency**: Ensures a consistent point of reference between your system and our API, helping to manage asynchronous processes or retry mechanisms.
* **Reconciliation**: Allows easy reconciliation of records if there are discrepancies or if any flow was left incomplete.

📢 We strongly recommend that partners always include the **partnerExternalId** when initiating a **Charge**.

## How to use

The majority of our entities support the `partnerExternalId`, for example, to start a `Charge` with a `partnerExternalId` You can do so by sending a POST request to the `/charges` endpoint with the following payload:

```json
{
  "chargePointId": 1,
  "payingTeamId": 1,
  "partnerExternalId": "MY_INTERNAL_ID_123",
  "partnerCustomPayload": {
    "field1": "1",
    "field2": [1, 2, 3]
  }
}
```

If You wish to filter changers with the `partnerExternalId`, it can be done via GET `/charges` endpoint with the following query parameters:

```curl
curl --request GET \
     --url 'https://partner-api.monta.com/api/v1/charges?partnerExternalId=MY_INTERNAL_ID&page=0&perPage=10' \
     --header 'accept application/json'
```

All endpoints follow the same standard for the `partnerExternalId`

## Benefits

Setting the `partnerExternalId` is the first step towards improving the reliability and consistency of your API integrations.

### Improved Error Recovery

In cases where a response is missing, or it times out, the client can use the `partnerExternalId` to query the state of an entity, even if the initial API response was not captured. This is particularly useful in payment capture or other time-sensitive transactions.

### Data Reconciliation

When reconciling data between the client’s system and our API, the `partnerExternalId` provides a simple and reliable way to match corresponding records.

### Easier Debugging and Support

Including `partnerExternalId` enables the Monta API team, to quickly find a particular resource during investigations.