> ## Documentation Index
> Fetch the complete documentation index at: https://developers.entri.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sell Enterprise API 

> Entri Sell Enterprise enables you to offer domain search, registration, and management directly within your platform.

## **Overview**

The **Entri Sell (Enterprise) API** enables you to offer domain search, registration, and management directly within your platform. By integrating with our API, you can sell domains to your customers without needing to manage ICANN compliance, registry integrations, or billing infrastructure.

Entri handles the provisioning and maintenance behind the scenes, while you focus on building a seamless customer experience.

***

## **Request Structure**

All requests to the Entri Sell Enterprise API must be made over HTTPS.

**Base URL:**

```txt theme={null}
https://api.goentri.com/enterprise/sell/{api-version}/{resource}
```

**General format:**

```txt theme={null}
{http-method} https://api.goentri.com/enterprise/sell/{api-version}/{resource}?{query-params}
```

**Request headers:**

* Authorization: Bearer `{access_token}` — required for authentication
* Accept: `application/json` — required, JSON is the only supported format
* Content-Type: `application/json` — required for requests with a body (POST, PUT)
* applicationId: `{your-application-name}` — identifies your integration

## **Authentication**

The Entri Sell Enterprise  API uses a **short-lived JWT** that you mint **server-side** using your **applicationId** and **secret**. Do **not** expose your secret in client code. The JWT expires after **60 minutes**.

### **1) Create a JWT**

**Endpoint**

POST `https://api.goentri.com/token`

**Headers**

`Content-Type: application/json`

**Body**

```json theme={null}
{
  "applicationId": "<YOUR_APPLICATION_ID>",
  "secret": "<YOUR_SECRET>"
}
```

**Response (200)**

```json theme={null}
{ "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..." }
```

JWT creation with applicationId and secret, 60-minute expiry.

### **2) Call the API with the JWT**

Include the JWT as a **Bearer** token, and pass your **applicationId** header on every request:

```
Authorization: Bearer <auth_token>
applicationId: <YOUR_APPLICATION_ID>
```

(Use of the JWT in Authorization and the applicationId header is shown across the Secure/Power API examples and applies here as well.)

**Example**

```bash theme={null}
curl -X GET "https://api.goentri.com/enterprise/sell/v1/domains/availability?domainName=example.com" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

### **Notes**

* Mint tokens **server-side** only; never ship your secret to the browser.
* Tokens expire after **60 minutes**—mint a fresh token as needed.

***

## **Domains – Search**

### **Check Domain Availability**

GET `/domains/availability` — Check if a domain is available.

**Params**

* `domain` (required): Domain name to check (e.g., example.com)

**Description**

Checks if a domain is available for registration.

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/domains/availability?domain=example.com" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "domain": "example.com",
  "availability": "AVAILABLE",
  "price": 12.99,
  "renewalPrice": 14.99
}
```

***

### **Retrieve Domain Suggestions**

GET `/domains/suggestions` — Returns domain suggestions based on the base domain name and TLDs.

**Params**

* `domain` (required): Base domain name for suggestions
* `tlds` (optional): Comma separated list of TLDs, e.g: `com,store,online`. If no `tlds` are present as the request parameters, the default `online,shop` will be used.

**Description**

Returns domain name suggestions for the given base domain name and TLDs.

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/domains/suggestions?domain=example&tlds=com,store,online" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "suggestions": [
    {
      "domain": "Exampleco.store",
      "price": 1,
      "renewalPrice": 99
    }
  ]
}
```

***

## **Domains – Management**

### **Retrieve List of Domains**

GET `/domains` — Retrieves list of all domains registered through the platform for the authenticated application.

**Authentication**

Required (JWT)

**Params**

* `page` (optional): Page number. Default first page (0)
* `size` (optional): Results per page. Default: 10
* `status` (optional): The status of the domain. Supported statuses: `payment_initiated, payment_successful, payment_failed, registration_in_progress, registered, transferred, transfer_started, transfer_completed, transfer_ack, transfer_success, transfer_failed`
* `domain` (optional): The domain name used in the search query.
* `application_id` (optional): The application\_id used in the search query.
* `from_date` (optional): ISO 8601 Date Format (YYYY-MM-DD) - Used for delimiting the start date of the search
* `to_date` (optional): ISO 8601 Date Format (YYYY-MM-DD) - Used for delimiting the end date of the search

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/domains?page=0&size=10&status=registered" \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -H "applicationId: <YOUR_APPLICATION_ID>" \
  -H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "items": [
    {
      "domainName": "domainname.com",
      "dnsRecords": [],
      "autoRenewed": true,
      "whoisPrivacy": false,
      "locked": false,
      "status": "registered",
      "createdAt": "2025-09-07T23:22:42.661936",
      "updatedAt": "2025-09-07T23:22:42.661936"
    }
  ],
  "total": 100,
  "page": 0,
  "limit": 10,
  "count": 10,
  "pages": 10,
  "nextPage": 1,
  "prevPage": null
}
```

***

### **Retrieve Single Domain**

GET `/domains/{domain_name}` — Retrieves detailed information about a specific domain.

**Path Parameters:**

* `domain_name` (required): Domain name to retrieve

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/domains/sampledomain.com" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "domainName": "sampledomain.com",
  "dnsRecords": [],
  "autoRenewed": true,
  "whoisPrivacy": false,
  "locked": false,
  "status": "payment_initiated",
  "createdAt": "2025-11-24T02:33:05.918266",
  "updatedAt": "2025-11-24T02:33:05.918266"
}
```

***

### **Update Domain Automatic Renewal Status**

PUT `/domains/{domain_name}/auto-renew` — Updates the auto-renewal status for a domain.

**Authentication**

Required (JWT)

**Path Parameters**

* `domain_name` (required): Domain name to set the renew

**Request Body**

```json theme={null}
{
  "autoRenew": true,
  "period": 12
}
```

**Example request**

```bash theme={null}
curl -X PUT \
"https://api.goentri.com/enterprise/sell/v1/domains/mydomain.com/auto-renew" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "autoRenew": true, "period": 12 }'
```

**Example response**

```json theme={null}
{
  "message": "Domain auto-renewal updated successfully"
}
```

***

### **Resend Registrant Verification Email**

POST `/domains/{domain_name}/resend-verification` — Resends the registrant verification email for a domain.

**Path Parameters**

* `domain_name` (required): Domain name

**Description**

Resends the registrant verification email for a domain.

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X POST \
"https://api.goentri.com/enterprise/sell/v1/domains/mydomain.com/resend-verification" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "message": "Verification email has been resent"
}
```

***

### **Retrieve Domain DNS Records**

GET `/domains/{domain_name}/dns-records` — Retrieves all DNS records for a domain

**Path Parameters**

* `domain_name` (required): Domain name

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/domains/mydomain.com/dns-records" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
[
  {
    "host": "@",
    "type": "A",
    "value": "192.168.1.1",
    "ttl": 3600
  }
]
```

***

### **Update Domain DNS Records**

PUT `/domains/{domain_name}/dns-records` — Updates DNS records for a given domain.

**Path Parameters**

* `domain_name` (required): Domain name

**Authentication**

Required (JWT)

**Request Body**

```json theme={null}
{
  "dns_records": [
    {
      "value": "ring-floor-1187.the.com",
      "host": "www",
      "ttl": 300,
      "type": "CNAME"
    },
    {
      "value": "_402962b5637f756da4ab7a0608067719.czrmfnbpdk.acm-validations.aws.",
      "host": "_a49d1d3b2b3fe27d0d002d533a751aee.www",
      "ttl": 300,
      "type": "CNAME"
    }
  ]
}
```

**Example request**

```bash theme={null}
curl -X PUT \
"https://api.goentri.com/enterprise/sell/v1/domains/mydomain.com/dns-records" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "dns_records": [ { "host":"www", "type":"CNAME", "value":"ring-floor-1187.the.com", "ttl":300 } ] }'
```

**Example response**

```json theme={null}
{
  "message": "DNS records updated successfully"
}
```

***

### **Domain Transfer In**

POST `/domains/{domain_name}/transfers/in` — Initiates the domain transfer from an external registrar.

**Path Parameters**

* `domain_name` (required): Domain name to be transferred.

**Description**

Initiates the domain transfer from an external registrar.

**Authentication**

Required (JWT)

**Request Body**

```json theme={null}
{
  "domain": "foo.com",
  "authorizationCode": "{AUTHORIZATION CODE}",
  "contactDetails": {
    "email": "renan@goentri.com",
    "fname": "Renan",
    "lname": "Alves",
    "phone": "+1-555-123-4567",
    "address": [
      "123 Main Street",
      "Suite 456"
    ],
    "city": "New York",
    "state": "NY",
    "country": "US",
    "pcode": "10001"
  }
}
```

The `{AUTHORIZATION CODE}` MUST be provided in order to successfully initiate the transfer due to the following purposes:

* **Validates** that the person initiating the transfer is the legitimate domain owner
* **Identifies** the legal owner or admin of the domain
* Acts as **authentication** between the losing registrar and gaining registrar

**Example request**

```bash theme={null}
curl -X POST "https://api.goentri.com/enterprise/sell/v1/domains/foo.com/transfers/in" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @transfer-in.json
```

**Example response**

```json theme={null}
{
  "domain": "foo.com",
  "transferId": "{TRANSFER_ID}",
  "transferStatus": "transfer_started",
  "transferType": "transfer_in"
}
```

***

### **Domain Transfer Out**

POST `/domains/{domain_name}/transfers/out` — Initiates the domain transfer out to an external registrar

**Path Parameters**

* `domain_name` (required): Domain name to be transferred to the gaining / external registrar

**Description**

Initiates the domain transfer out to an external registrar

**Authentication**

Required (JWT)

**Request Body**

```json theme={null}
{
  "domain": "foo.com"
}
```

**Example request**

```bash theme={null}
curl -X POST "https://api.goentri.com/enterprise/sell/v1/domains/foo.com/transfers/out" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "domain": "foo.com" }'
```

**Example response**

```json theme={null}
{
  "domain": "foo.com",
  "authCode": "{AUTHORIZATION CODE}",
  "transferStatus": "transfer_started",
  "transferType": "transfer_out"
}
```

## **Orders**

### **Validate Whois Contacts**

POST `/domains/contacts/validate` — Validates WHOIS contact information before domain registration.

**Description**

Validates WHOIS contact information before domain registration.

**Authentication**

Required (JWT)

**Request Body**

```json theme={null}
{
  "email": "renan@goentri.com",
  "fname": "Renan",
  "lname": "Alves",
  "phone": "+1-555-123-4567",
  "address": [
    "123 Main Street",
    "Suite 456"
  ],
  "city": "New York",
  "state": "NY",
  "country": "US",
  "pcode": "10001",
  "organization": "Example Corporation",
  "type": "PERSON"
}
```

**Example request**

```bash theme={null}
curl -X POST "https://api.goentri.com/enterprise/sell/v1/domains/contacts/validate" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @contacts.json
```

**Example response**

```json theme={null}
{
  "message": "Whois contact validated and successfully created",
  "content": {
    "created": "2025-12-17T14:06:31.000+0100",
    "updated": "2025-12-17T14:06:31.000+0100",
    "id": 24047757,
    "owner": {
      "context": 4,
      "user": "1352400449"
    },
    "updater": {
      "context": 4,
      "user": "1352400449"
    },
    "alias": "Renan-Alves1",
    "type": "PERSON",
    "organization": "Example Corporation",
    "city": "New York",
    "country": "US",
    "state": "NY",
    "email": "renan@goentri.com",
    "protection": "SHOW_NONE",
    "domainsafe": false,
    "fname": "Renan",
    "lname": "Alves",
    "address": [
      "123 Main Street",
      "Suite 456"
    ],
    "pcode": "10001",
    "phone": "+1-555-1234567"
  }
}
```

***

### **Retrieve Orders**

GET `/orders` — Retrieves list of all orders for the authenticated application.

**Query Parameters**

* `page` (optional): Page number. Default first page (0)
* `size` (optional): Results per page. Default: 10
* `status` (optional): The status of the domain. Supported statuses: `payment_initiated, payment_successful, payment_failed, registration_in_progress, registered, transferred, transfer_started, transfer_completed, transfer_ack, transfer_success, transfer_failed`
* `domain` (optional): The domain name used in the search query.
* `application_id` (optional): The application\_id used in the search query.
* `from_date` (optional): ISO 8601 Date Format (YYYY-MM-DD) - Used for delimiting the start date of the search
* `to_date` (optional): ISO 8601 Date Format (YYYY-MM-DD) - Used for delimiting the end date of the search

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/orders?page=0&size=10" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "items": [
    {
      "orderId": "5cf0cd4a-6a9f-4b53-8b11-7fe2a89e75df",
      "orderStatus": "registered",
      "customerEmail": "customer@email.com",
      "items": [
        {
          "orderItemId": "fe5624c3-d18d-4144-b1ab-5ef4711317e5",
          "domainName": "foo.com",
          "dnsRecords": [],
          "autoRenewed": true,
          "whoisPrivacy": false,
          "locked": false,
          "status": "registered",
          "createdAt": "2025-12-09T16:27:53.523047",
          "updatedAt": "2025-12-09T16:27:53.523047"
        }
      ]
    }
  ],
  "total": 100,
  "page": 0,
  "limit": 10,
  "count": 10,
  "pages": 10,
  "nextPage": 1,
  "prevPage": null
}
```

***

### **Place New Order**

POST `/orders` — Creates a new domain order

**Description**

Creates a new domain order

**Authentication**

Required (JWT)

**Request Body**

<Note>
  **`contactDetails` requirement depends on your application's `x-lightning-mode` setting:**

  * If `x-lightning-mode` is **enabled**, `contactDetails` is not required. The system will use the default contact info configured in **Application Settings > Sell Contact Info**. If sent, it will be ignored.
  * If `x-lightning-mode` is **disabled**, `contactDetails` is mandatory.
</Note>

```json theme={null}
{
  "domain": "example.com",
  "email": "customer@example.com",
  "userId": "ca8d6947-6232-44f7-af37-6501edad00aa",
  "contactDetails": {
    "type": "PERSON",
    "fname": "John",
    "lname": "Doe",
    "address": [
      "123 Main Street"
    ],
    "city": "New York",
    "pcode": "12345",
    "country": "US",
    "state": "NY",
    "phone": "+1.5551234567",
    "email": "customer@example.com"
  },
  "defaultDnsRecords": [
    {
      "host": "@",
      "type": "A",
      "value": "192.168.1.1"
    }
  ]
}
```

| Field               | Required    | Description                                                                                                    |
| ------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `domain`            | Yes         | The domain name to register (e.g. `example.com`)                                                               |
| `email`             | Yes         | Customer's email address                                                                                       |
| `userId`            | No          | ID of the user to associate with the order                                                                     |
| `contactDetails`    | Conditional | WHOIS contact information. Required when `x-lightning-mode` is disabled; ignored when enabled. See note above. |
| `defaultDnsRecords` | No          | DNS records to apply to the domain upon registration                                                           |

**Example request**

```bash theme={null}
curl -X POST "https://api.goentri.com/enterprise/sell/v1/orders" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @order.json
```

**Example response**

```json theme={null}
{
  "orderId": "21b363fb-c8c0-427e-8d2d-91658f806471",
  "userId": null,
  "domain": "example.com",
  "status": "registration_in_progress",
  "contactDetails": {
    "type": "PERSON",
    "fname": "John",
    "lname": "Doe",
    "address": ["123 Main Street"],
    "city": "New York",
    "pcode": "12345",
    "country": "US",
    "state": "NY",
    "phone": "+1.5551234567",
    "email": "customer@example.com"
  },
  "createdAt": "2026-03-03T12:27:19.751544",
  "dnsRecords": [],
  "pricing": {
    "purchasePrice": 19,
    "renewalPrice": 24,
    "currency": "USD",
    "billingPeriod": 1
  }
}
```

| Field                   | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `orderId`               | Unique identifier for the order                        |
| `userId`                | ID of the user associated with the order, if any       |
| `domain`                | The domain name being registered                       |
| `status`                | Current order status (e.g. `registration_in_progress`) |
| `contactDetails`        | WHOIS contact information used for the registration    |
| `createdAt`             | ISO 8601 timestamp of when the order was created       |
| `dnsRecords`            | DNS records applied to the domain                      |
| `pricing.purchasePrice` | One-time purchase price                                |
| `pricing.renewalPrice`  | Annual renewal price                                   |
| `pricing.currency`      | Currency code (e.g. `USD`)                             |
| `pricing.billingPeriod` | Billing period in years                                |

***

### **Retrieve Single Order**

GET `/orders/{order_id}` — Retrieves detailed information about a specific order.

**Description**

Retrieves detailed information about a specific order.

**Path Parameters**

* `order_id` (required): Order UUID

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/orders/5c819665-2f7a-48c7-8c7b-fabd46f9235f" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "orderId": "5c819665-2f7a-48c7-8c7b-fabd46f9235f",
  "orderStatus": "registered",
  "customerEmail": "customer@email.com",
  "items": [
    {
      "orderItemId": "5ea01588-509f-4245-bbe9-6f37c3047f0c",
      "domainName": "foo.com",
      "dnsRecords": [],
      "autoRenewed": true,
      "whoisPrivacy": false,
      "locked": false,
      "status": "registered",
      "createdAt": "2025-12-09T16:27:53.523047",
      "updatedAt": "2025-12-09T16:27:53.523047"
    }
  ]
}
```

Where `status` is one of the supported: `payment_initiated, payment_successful, payment_failed, registration_in_progress, registered, transferred, transfer_started, transfer_completed, transfer_ack, transfer_success, transfer_failed`

***

### **Check Order Status**

GET `/orders/{order_id}/status` — Checks and updates the current status of an order.

**Description**

Checks and updates the current status of an order.

**Path Parameters**

* `order_id` (required): Order UUID

**Authentication**

Required (JWT)

**Example request**

```bash theme={null}
curl -X GET \
"https://api.goentri.com/enterprise/sell/v1/orders/5c819665-2f7a-48c7-8c7b-fabd46f9235f/status" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "applicationId: <YOUR_APPLICATION_ID>" \
-H "Accept: application/json"
```

**Example response**

```json theme={null}
{
  "status": "registered"
}
```

Where `status` is one of the supported: `payment_initiated, payment_successful, payment_failed, registration_in_progress, registered, transferred, transfer_started, transfer_completed, transfer_ack, transfer_success, transfer_failed`

***

## Webhook Notifications

When your users go through the Sell flow, Entri will send you webhook notifications to update you on their progress and the status of their purchase. To learn more about the configuration and webhook notifications, please visit our [webhook documentation page](https://developers.entri.com/webhooks).

***

## **Errors**

All errors from the API are returned in a standard JSON structure. The respective HTTP status code is also returned part of the HTTP response headers.

**Format:**

```json theme={null}
{
  "message": "Error description"
}
```

* `message` – human-readable description of the error

***

## **Security**

### **IP Safelisting**

The Entri Sell Enterprise  API supports optional IP safelisting. If configured, only requests from approved IPs or CIDR ranges will be accepted.

To request or update your safelist, please contact our support team with the IP addresses you would like to register.

***

## **Billing Integration**

### **Link to Entri Billing from Your Customer Dashboard**

For a streamlined customer experience, you can provide your users with direct access to Entri’s billing management interface directly from your platform.

Entri provides an API endpoint that returns a **short-lived, authenticated billing link** for a specific user. Your backend should request this link dynamically and then redirect the user to it.

#### **Get Authenticated Billing Link**

GET `/billing/link` — Returns an authenticated billing URL for a customer.

**Authentication**

Required (JWT)

**Query Parameters**

* `email` (required): The customer’s email address associated with their Entri account
* `returnUrl` (required): The URL where the user should be redirected after leaving the billing portal

**Example request**

```bash theme={null}
curl --location 'https://api.goentri.com/enterprise/sell/v1/billing/link?email=akhil%40goentri.com&returnUrl=https%3A%2F%2Fwww.entri.com' \
  -H 'Authorization: Bearer <AUTH_TOKEN>' \
  -H 'applicationId: <YOUR_APPLICATION_ID>' \
  -H 'Accept: application/json'
```

**Example response**

```json theme={null}
{
  "url": "https://billing.stripe.com/p/session/<SIGNED_TOKEN>"
}
```

Use the returned `url` to redirect the user or open the billing experience in a new browser tab. The link is scoped to the authenticated user and expires automatically.

***