> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.americanexpress.ferndocs.com/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 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 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() ```