> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Create the listing of an app

POST https://api.letsdeel.com/rest/oauth2-apps/{app_id}/listing
Content-Type: application/json

Creates the App Store listing of an app that belongs to your organization. Use it once per app, before you edit the listing. The listing starts empty and unpublished. Returns the listing.

 **Token scopes**: `apps:write`

 **Beta**: this version requires the `X-Beta: true` request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2027-02-18.

Reference: https://developer.deel.com/api/reference/endpoints/apps/create-app-listing-v-2026-11-18

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Path parameters

- `app_id` (string, required) — Unique identifier of the app.

### Headers

- `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`.
  - Allowed values: `true`

### Body (application/json)

This endpoint expects an object.

- `data` (Oauth2AppsAppIdListingPostRequestBodyContentApplicationJsonSchemaData, required) — The listing to create.

## Response

### 201

The new listing.

- `data` (Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaData, required) — The App Store listing of an app.

## Errors

### 400 Bad Request Error

Bad Request. The app id or a field is invalid.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 401 Unauthorized Error

Unauthorized. Authentication credentials were missing or invalid.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 403 Forbidden Error

Forbidden. You do not have permission to access this resource.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 404 Not Found Error

Not Found. No app with this id belongs to your organization.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 409 Conflict Error

Conflict. The app already has a listing, or the name or slug is used by another listing.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 429 Too Many Requests Error

Too Many Requests. The rate limit has been exceeded.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

### 500 Internal Server Error

Internal Server Error. An unexpected error occurred.

- `errors` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems, required) — The list of errors that caused the request to fail.

## Types

### Oauth2AppsAppIdListingPostRequestBodyContentApplicationJsonSchemaData

The listing to create.

- `name` (string, required) — Name of the listing in the App Store. It must be unique.
- `slug` (string, optional) — Unique short name used in the address of the listing. Lowercase letters, digits and dashes. Defaults to the name written that way.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaData

The App Store listing of an app.

- `name` (string, required) — Name of the listing in the App Store.
- `app_id` (string, required) — Unique identifier of the app the listing belongs to.
- `status` (enum, required) — Whether the listing is live in the App Store. It stays `published` while a newer revision is reviewed.
  - Allowed values: `published`, `unpublished`
- `faq_url` (string, required, nullable) — FAQ of the app.
- `logo_url` (string, required, nullable) — URL of the logo of the revision in `latest_revision`, as saved. Null only when no logo has been set. For some older listings the URL is a temporary link that stops working after about an hour.
- `categories` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataCategoriesItems, required) — App Store categories of the revision.
- `highlights` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataHighlightsItems, required) — Highlights shown on the store page.
- `works_with` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataWorksWithItems, required) — Deel products the app works with.
- `how_it_works` (string, required, nullable) — How the app works.
- `media_gallery` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataMediaGalleryItems, required) — Images and videos of the revision in `latest_revision`, as saved. Empty when none has been set.
- `support_email` (string, required, nullable) — Where customers reach your support.
- `what_it_syncs` (list of string, required) — What the app syncs.
- `demo_video_url` (string, required, nullable) — Demo video of the app.
- `latest_revision` (Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataLatestRevision, required, nullable) — The version of the listing you are working on or that is under review. Null until the listing has content.
- `escalation_email` (string, required, nullable) — Where Deel escalates urgent issues.
- `landing_page_url` (string, required, nullable) — Landing page of the app.
- `short_description` (string, required, nullable) — Tagline shown on the listing card.
- `support_resources` (list of Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataSupportResourcesItems, required) — Support links shown on the store page.
- `first_published_at` (string, required, nullable) — When the listing was first approved. Null until then.
- `pricing_description` (string, required, nullable) — What the app costs.
- `product_description` (string, required, nullable) — What the app does.
- `main_description_body` (string, required, nullable) — Body of the main description on the store page.
- `main_description_title` (string, required, nullable) — Title of the main description on the store page.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, required) — Machine-readable error code.
- `message` (string, required) — Human-readable description of the error.
- `details` (Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItemsDetails, optional) — Additional information about the error, when available.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataCategoriesItems

- `id` (integer, optional) — Unique identifier of the category.
- `name` (string, optional) — Name of the category.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataHighlightsItems

- `text` (string, optional) — Text of the highlight.
- `title` (string, optional, nullable) — Title of the highlight.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataWorksWithItems

- `url` (string, optional, nullable) — Address of the link.
- `name` (string, optional) — Name of the link.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataMediaGalleryItems

- `url` (string, optional) — Public URL of the item.
- `type` (enum, optional) — Whether the item is an image or a video.
  - Allowed values: `image`, `video`
- `caption` (string, optional, nullable) — Caption of the item.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataLatestRevision

The version of the listing you are working on or that is under review. Null until the listing has content.

- `status` (enum, optional) — Where the revision stands. Only a draft can be edited and submitted.
  - Allowed values: `draft`, `in_review`, `published`, `rejected`
- `review_notes` (string, optional, nullable) — The reviewer’s notes when the revision was rejected.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaDataSupportResourcesItems

- `url` (string, optional, nullable) — Address of the link.
- `name` (string, optional) — Name of the link.

### Oauth2AppsAppIdListingPostResponsesContentApplicationJsonSchemaErrorsItemsDetails

Additional information about the error, when available.

## Examples

**Request**

```json
{
  "data": {
    "name": "Payroll sync"
  }
}
```

**Response**

```json
{
  "data": {
    "name": "Payroll sync",
    "app_id": "00000000-0000-0000-0000-000000000000",
    "status": "published",
    "faq_url": "https://example.com/faq",
    "logo_url": "https://assets.example.com/logos/abc/logo.png",
    "categories": [
      {
        "id": 182,
        "name": "Collaboration"
      }
    ],
    "highlights": [
      {
        "text": "Syncs every hour",
        "title": "Automatic sync"
      }
    ],
    "works_with": [
      {
        "url": "https://example.com/docs",
        "name": "Setup guide"
      }
    ],
    "how_it_works": "Sign in and authorize.",
    "media_gallery": [
      {
        "url": "https://assets.example.com/gallery/abc/screenshot.png",
        "type": "image",
        "caption": "Dashboard"
      }
    ],
    "support_email": "support@example.com",
    "what_it_syncs": [
      "Worker Profiles"
    ],
    "demo_video_url": "https://example.com/demo",
    "latest_revision": {
      "status": "in_review",
      "review_notes": "Add a support email and a demo video, then resubmit."
    },
    "escalation_email": "escalations@example.com",
    "landing_page_url": "https://example.com",
    "short_description": "Sync timesheets to payroll",
    "support_resources": [
      {
        "url": "https://example.com/docs",
        "name": "Setup guide"
      }
    ],
    "first_published_at": "2026-10-26T10:30:00.000Z",
    "pricing_description": "Free for Deel customers.",
    "product_description": "Syncs approved timesheets to your payroll system.",
    "main_description_body": "<p>Keep payroll in sync.</p>",
    "main_description_title": "Payroll sync"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing"

payload = { "data": { "name": "Payroll sync" } }
headers = {
    "X-Beta": "true",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing';
const options = {
  method: 'POST',
  headers: {
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"name":"Payroll sync"}}'
};

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://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing"

	payload := strings.NewReader("{\n  \"data\": {\n    \"name\": \"Payroll sync\"\n  }\n}")

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

	req.Header.Add("X-Beta", "true")
	req.Header.Add("Authorization", "Bearer <token>")
	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://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing")

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

request = Net::HTTP::Post.new(url)
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"name\": \"Payroll sync\"\n  }\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://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"name\": \"Payroll sync\"\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing', [
  'body' => '{
  "data": {
    "name": "Payroll sync"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Beta' => 'true',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"name\": \"Payroll sync\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Beta": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": ["name": "Payroll sync"]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/oauth2-apps/00000000-0000-0000-0000-000000000000/listing")! 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()
```