> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.americanexpress.ferndocs.com/personalized-services/dotamex/api-reference/create-a-short-url/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server.

# Create a short URL

POST https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping
Content-Type: application/json

Reference: https://developer.americanexpress.ferndocs.com/personalized-services/dotamex/api-reference/create-a-short-url

## Servers

- `https://apigw-dev.americanexpress.com/dotamex/v1/empurl` (E1, default)
- `https://apigw-qa.americanexpress.com/dotamex/v1/empurl` (E2)
- `https://apigw.americanexpress.com/dotamex/v1/empurl` (E3)
- `https://apigwm-qa.americanexpress.com/dotamex/v1/empurl` (Sandbox)
- `https://apigwm.americanexpress.com/dotamex/v1/empurl` (Production)

## Request

### Body (application/json)

This endpoint expects a mappingRequest.

- `longUrl` (string, required) — The URL that the user should be redirected to. Must be a valid URL.
- `expDate` (string, required) — The date that the shortUrl will expire on. Expired URLs will redirect users to the [URL not found page](https://www.americanexpress.com/us/homepage/error.html). We generally recommend you pick a expiration date that is twice as long as you expect the URL to be 'useful' for. See these examples. If you are generating one-off links (OTP, safe key, user specific American Express offer, etc.) which will be used in the next three days, then pick a expiration date of one week. Alternatively if you are generating links for a marketing campaign where the campaign is expected to finish one year from now, then give an expiration date of two years.
- `path` (string, optional) — This is to request a specific "vanity" URL. If provided, we will try and register the link on this path. If the path is not available for the requested domain (i.e., it was already taken), the request will return an HTTP 400 error.
- `domain` (enum, optional, default: m) — This is the domain to be used for the shortURL in E3.
  - Allowed values: `m`, `go`, `bca.m`, `t.m`
- `params` (params, optional) — This is to provide additional metadata about the URL. It also can be used to set advanced options for the URL, like cache strategy or retention period.
- `user` (string, optional) — The ADS ID of an American Express colleague responsible for this URL. This will be used to contact you about your URL.
- `userGroup` (string, optional) — This is to provide information about the user submitting the DotAmex registration request; to be referenced for link expiration communication.

## Response

### 200

Success response.

- `longUrl` (string, required) — The URL that the user should be redirected to. Must be a valid URL.
- `shortUrl` (string, required) — The returned shortUrl will only be "short" in E3, where the m, go, bca.m, t.m DNS records are in place. In E1, the value will begin with empurlshortener-dev.americanexpress.com. In E2, the value will begin with empurlshortener-qa.americanexpress.com.
- `expDate` (string, required) — The date that the shortUrl will expire on. Expired URLs will redirect users to the [URL not found page](https://www.americanexpress.com/us/homepage/error.html). We generally recommend you pick a expiration date that is twice as long as you expect the URL to be 'useful' for. See these examples. If you are generating one-off links (OTP, safe key, user specific American Express offer, etc.) which will be used in the next three days, then pick a expiration date of one week. Alternatively if you are generating links for a marketing campaign where the campaign is expected to finish one year from now, then give an expiration date of two years.
- `params` (params, optional) — This is to provide additional metadata about the URL. It also can be used to set advanced options for the URL, like cache strategy or retention period.

## Errors

### 400 Bad Request Error

Bad request.

- `any`

## Types

### params

This is to provide additional metadata about the URL. It also can be used to set advanced options for the URL, like cache strategy or retention period.

- `campaignId` (string, optional) — This is the campaign name or ID that you want to be associated with the link. This is used for tracking and analytics purposes.
- `country` (string, optional) — This is the country that you want to be associated with the link. This is used for tracking and analytics purposes.
- `channel` (string, optional) — This is the channel that you want to be associated with the link. This is used for tracking and analytics purposes.
- `da.redirect.cache-control` (string, optional) — The only valid option is no-store. This prevents the shortUrl from using the cache. If this key is not set, the default behavior is to automatically cache the URL.
- `da.couch.retention` (string, optional) — The valid options are numbers zero or greater. This is the number of days after a link expires that historical data for the Short URL is kept.

## Examples

**Request**

```json
{
  "longUrl": "https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards",
  "expDate": "2026-07-07T18:08:10Z"
}
```

**Response**

```json
{
  "longUrl": "https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards",
  "shortUrl": "m.amex/b39FhZ",
  "expDate": "2026-07-07T18:08:10Z",
  "params": {
    "campaignId": "campaign",
    "country": "US",
    "channel": "channel"
  }
}
```

**SDK Code**

```python
import requests

url = "https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping"

payload = {
    "longUrl": "https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards",
    "expDate": "2026-07-07T18:08:10Z"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"longUrl":"https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards","expDate":"2026-07-07T18:08:10Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping"

	payload := strings.NewReader("{\n  \"longUrl\": \"https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards\",\n  \"expDate\": \"2026-07-07T18:08:10Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"longUrl\": \"https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards\",\n  \"expDate\": \"2026-07-07T18:08:10Z\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping")
  .header("Content-Type", "application/json")
  .body("{\n  \"longUrl\": \"https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards\",\n  \"expDate\": \"2026-07-07T18:08:10Z\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping', [
  'body' => '{
  "longUrl": "https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards",
  "expDate": "2026-07-07T18:08:10Z"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"longUrl\": \"https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards\",\n  \"expDate\": \"2026-07-07T18:08:10Z\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "longUrl": "https://www.americanexpress.com/us/credit-cards/business/corporate-credit-cards",
  "expDate": "2026-07-07T18:08:10Z"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://apigw-dev.americanexpress.com/dotamex/v1/empurl/mapping")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```