# Fetch an entity

URL: https://docs.sparklayer.io/ignite/api/fetch-entity
Operation: `POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}` (operationId `getEntity`)
OpenAPI spec: https://docs.sparklayer.io/openapi/ignite.yaml

Fetch an entity from the platform.

`POST /v1/{siteEnv}/{siteId}/sync/{syncDataType}/{entityId}`

> This is an Ignite endpoint: your integration service implements it and SparkLayer calls it.

### Request SparkLayer sends

```http
POST /v1/live/bobs-store/sync/products/1234567890 HTTP/1.1
Host: ignite.example.com
Content-Type: application/json

{
  "payload": "<payload>"
}
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `siteEnv` | string | Yes | The SparkLayer environment the request is for, such as `live`. Store it, with the site ID, when SparkLayer connects your platform. Example: `live` |
| `siteId` | string | Yes | The SparkLayer site ID the request is for, such as `bobs-store`. Store it, with the environment, when SparkLayer connects your platform. Length: min 1. Example: `bobs-store` |
| `syncDataType` | "customers" \| "products" \| "purchases" \| "stock" | Yes | The type of entity to fetch. Example: `products` |
| `entityId` | string | Yes | The entity's ID on your platform. Example: `1234567890` |

### Request body (`application/json`) (optional)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | string \| null | | Optional - the payload to send back to the integration during the item sync |

```json
{
  "payload": "<payload>"
}
```

### Responses your service returns

#### 200: Entity fetched successfully

One of these:

**CustomerData**: Customer data representing the SparkLayer Customer object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `customer_v2` | string | | base64 encoded string |
| `customer_v2_deactivate` | boolean | | whether or not to deactivate the customer |

**ProductData**: Product data representing the SparkLayer Product object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `product_v2_delete` | boolean | | whether or not to delete the product |
| `product_v2_discontinue` | boolean | | whether or not to discontinue the product |
| `product_v2` | string | | base64 encoded string |
| `batch_stock_v1` | string | | base64 encoded string |
| `batch_pricing_v1` | string | | base64 encoded string |

**PurchaseData**: Purchase data representing the SparkLayer Purchase object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `purchase_v1` | string | | base64 encoded string |

**StockData**: Stock data representing the SparkLayer Stock object.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `batch_stock_v1` | string | | base64 encoded string |

```json
{
  "external_id": "<external_id>",
  "external_url": "<external_url>",
  "visible_name": "<visible_name>",
  "customer_v2": "<customer_v2>",
  "customer_v2_deactivate": true
}
```

#### 400: Invalid request, such as a payload that cannot be decoded

#### 401: Auth Failure

#### 404: Not Found

One of these:

- **Problem**: the standard error body (below).

**EntityDoesNotExist**: The integration indicated that the entity does not exist.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-does-not-exist" | Yes | |
| `status` | 404 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 404,
  "detail": "<detail>"
}
```

#### 422: Unprocessable entity. The sync service does not check the content type, and the SparkLayer integrations send this body as application/json.

`application/problem+json`:

One of these:

- **Problem**: the standard error body (below).

**EntityConfigurationError**: The integration indicated that the entity is not correctly configured and therefore cannot be synced.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-configuration-error" | Yes | |
| `status` | 422 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `api_response` | string | | API response error for sync log |
| `friendly_error` | string | | Friendly error message to display in sync log |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 422,
  "detail": "<detail>"
}
```

`application/json`:

One of these:

- **Problem**: the standard error body (below).

**EntityConfigurationError**: The integration indicated that the entity is not correctly configured and therefore cannot be synced.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | "entity-configuration-error" | Yes | |
| `status` | 422 | | |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |
| `external_id` | string | | External id of the entity |
| `external_url` | string | | A url to access to entity on |
| `visible_name` | string | | A display name for the entity |
| `api_response` | string | | API response error for sync log |
| `friendly_error` | string | | Friendly error message to display in sync log |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 422,
  "detail": "<detail>"
}
```

#### 429: Rate limit exceeded

#### 500: System Exception

#### Other statuses: Error Response

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string (uri) | Yes | A URI reference that identifies the problem. |
| `title` | string | Yes | A short, human-readable summary of the problem type. |
| `status` | integer | | The HTTP status code generated by the origin server for this occurrence of the problem. |
| `detail` | string | | A human-readable explanation specific to this occurrence of the problem. |

```json
{
  "type": "about:blank",
  "title": "invalid-request-contents",
  "status": 0,
  "detail": "<detail>"
}
```