# Idempotency

An API is considered idempotent when repeated identical requests yield the same outcome without causing any errors.
This indicates that calling the API multiple times has the same effect as calling it just once. 

All `GET`, `PUT`, and `DELETE` requests to Spotnana APIs are idempotent by default.
However, certain `POST` requests that create a resource on the server side will not exhibit the same behavior.
For example, the [Create company](/openapi/companyapi#operation/createCompany) API
is not idempotent.

## Handling Non-Idempotent POST APIs

`POST` APIs used for resource creation are not idempotent (e.g., [Create company](/openapi/companyapi#operation/createCompany) API).
To address scenarios where a client may accidentally call such `POST` APIs several consecutive times, these APIs can
contain an `externalId` as part of the request. In case of network errors, you can still retrieve the resource identifier using this `externalId`
(provided if the resource creation was successful). 

To explain this scenario with an example, consider the [Create company](/openapi/companyapi#operation/createCompany) API.
When you're calling this API to create a new company, you can include an optional `externalId` in the request to specify an external identifier.
The first API call will create a new resource. However, since the [Create company](/openapi/companyapi#operation/createCompany) API
is not idempotent, you may encounter an error if you run this API with consecutive identical requests.
In such cases, to fetch the newly created resource information, you can use the `externalId` on the
[List companies](/openapi/companyapi#operation/listCompanies) API. 

The following code snippet is a sample `curl` request of the [List companies](/openapi/companyapi#operation/listCompanies) API
where the `externalId` is added as a query parameter.


```
curl -i -X GET \
  'https://apis.spotnana.com/v2/companies?externalId=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
```

> **Note:** Most APIs have a unique identifier (e.g., a unique company name) which prevents the creation
of duplicate resources. The `externalId` is an additional measure to make sure the API client doesn't create
a duplicate record on the server.