# Invoke mappings
Source: https://www.stedi.com/docs/edi-platform/mappings/transform-json-documents

***

title: Invoke mappings
sidebarTitle: "Invoke"
----------------------

<Note>
  This functionality is available in a Stedi module. [Contact us](https://www.stedi.com/contact) for details.
</Note>

Once you [create a mapping](/edi-platform/mappings/manage-mappings/ui-guide), you can use it to transform JSON into a custom shape.

## Inbound - Mappings API

You can use webhooks to automatically send transaction processed events to any API endpoint. Then, you can use the [Map Transaction Output](/edi-platform/api-reference/get-map-transaction-output) endpoint to return the mapped output of the processed inbound transaction.

You can also call the [Invoke Mapping API](/edi-platform/api-reference/post-invoke-mapping) to transform JSON into a custom shape.

## Outbound - Create Outbound Transaction

Call the [Create Outbound Transaction](/edi-platform/api-reference/post-transactions) endpoint with a mapping ID. Stedi uses the specified mapping to automatically transform your system’s data into Guide JSON before generating and delivering the EDI file.

### Payload validation

By default, the Mappings API doesn't validate incoming or transformed JSON.

When you enable **strict validation mode**, Mappings uses the [source schema](/edi-platform/mappings/manage-mappings/mapping-definition#source-schema)
to validate the input JSON payload and the [target schema](/edi-platform/mappings/manage-mappings/mapping-definition#target-schema)
to validate the outgoing JSON payload.

To enable strict validation mode, set the `validation_mode` query parameter to `strict`. The following example shows how to enable strict validation mode in your request.

```http
POST https://mappings.us.stedi.com/2021-06-01/mappings/01AB3DEF4GHIJ5KL67MNOP8QR9/map?validation_mode=strict HTTP/1.1
```

**Success and failure responses**

* If the mapping is evaluated successfully and there are no validation failures, the body of the response is the mapped document.
* If the evaluation of the mapping expression fails, then validation of the input and the output is not applied, the response is a 400 error with the `mapping_failed` code and no `validation_errors` object.
* If validation of the input or output payload fails, the response is a 400 error with the `validation_failed` code and `validation_errors` object.

### Example request

The following example shows a request to the [Invoke Mapping API](/edi-platform/api-reference/post-invoke-mapping). The request body is the JSON document that you want to map.

```http
POST https://mappings.us.stedi.com/2021-06-01/mappings/01AB3DEF4GHIJ5KL67MNOP8QR9/map HTTP/1.1
"Authorization: ${STEDI_API_KEY}"
Content-Type: application/json

{
  "quantity": 15,
  "unit_price": 2.50
}
```

The body of the response is the mapped document.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "total": 37.50
}
```

<Note>
  You must make a separate request to the API for each JSON document. Visit
  [Concurrency](#api-concurrency) for more details.
</Note>

## Send a compressed payload to the API

To send a `gzip` compressed payload to the Mappings API, set the `Content-Encoding` header to the value of `gzip`. Mappings API currently only supports `gzip` compression.

Note that the [maximum document size limit](/edi-platform/mappings/limits) **is applied after decompressing the content of the payload**. If the decompressed payload of a given request is larger than the maximum document size limit, the Mappings API will reject the request.

The following is an example written in [TypeScript](https://www.typescriptlang.org/) of creating mapping and sending a `gzip` compressed payload to the `/map` endpoint.

```ts
import axios from "axios";
import { gzipSync } from "zlib";

const STEDI_API_KEY = "YOUR_API_KEY";
const rootURL = "https://mappings.us.stedi.com/2021-06-01/mappings";
const headers = { Authorization: `Key ${STEDI_API_KEY}` };

async function doRequest() {
  const mapping = {
    name: "GzipPayloadMapping",
    mapping: `{"Hello": keyFromSource}`,
    type: "only_mapped_keys",
  };

  const createMappingResponse = await axios.post(rootURL, mapping, { headers });

  const payload = gzipSync(JSON.stringify({ keyFromSource: "World!" }));
  const mapResponse = await axios.post(
    `${rootURL}/${createMappingResponse.data.id}/map`,
    payload,
    {
      headers: {
        ...headers,
        "Content-Encoding": "gzip",
      },
    },
  );

  console.log(mapResponse.data);
}

async function main() {
  try {
    await doRequest();
  } catch (e) {
    console.log(e);
  }
}

main();
```

## API concurrency

Mappings allows up to 200 concurrent requests, so if you need to map 200 documents or less, you can send them all at once. If you need to map more than 200 documents, you should make sure that you don't exceed 1000 requests per second. Also keep in mind that there's a maximum of one million requests per day.

If you make more requests than Mappings is able to handle, you will receive a `429 Too Many Requests` response.

* Keep track of how many outstanding requests you have. Don't send any new requests if you have 200 or more.
* Keep track of how many total requests you've sent in a day and make sure it doesn't exceed 1,000,000.
* Keep a timestamp for every successful response you receive. When sending a new request, first check the timestamp for 1000 requests ago. If it's less than a second ago, wait until the second has passed before making a new request.
* If you receive a 429 Too Many Requests response, wait for one second before sending new requests. If you still get back 429 after waiting for one second, then wait for two seconds. If that's not enough wait for four, then eight, etc.
* If you receive a 429 Too Many Requests response, add the document back into the list of documents that you need to map. Don't resend the request immediately.