Listings

In Directify, listings are the items that appear in your directory. These can be tools, services, products, or any other items you want to showcase. The API endpoints use “projects” in the URL, but they refer to listings in your directory.

Get Directory Listings

Retrieve all listings for a specific directory with pagination.

GET /api/directories/{directory_id}/projects

Parameters:

directory_id (integer, required): The ID of the directory
page (integer, optional): Page number for pagination (default: 1)

Response:

{
  "data": [
    {
      "id": 1,
      "name": "React.js",
      "slug": "react-js",
      "description": "A JavaScript library for building user interfaces",
      "content": "Full content body with HTML...",
      "url": "https://reactjs.org",
      "image_url": "https://example.com/images/react.jpg",
      "logo_url": "https://example.com/logos/react.png",
      "logo_alt_text": "React.js Logo",
      "image_alt_text": "React.js Homepage",
      "additional_image_urls": ["https://example.com/gallery1.jpg", "https://example.com/gallery2.jpg"],
      "additional_images_urls": ["https://cdn.example.com/gallery1.jpg", "https://cdn.example.com/gallery2.jpg"],
      "video_url": null,
      "video_thumbnail_url": null,
      "phone_number": "+1 (555) 123-4567",
      "email": "contact@reactjs.org",
      "address": "1 Hacker Way, Menlo Park, CA",
      "latitude": 37.4847,
      "longitude": -122.1477,
      "social_links": {
        "twitter": "https://twitter.com/reactjs",
        "github": "https://github.com/facebook/react"
      },
      "categories": [
        {
          "id": 1,
          "title": "Frontend",
          "parent_title": "Web Development"
        }
      ],
      "tags": [
        {
          "id": 1,
          "title": "Open Source",
          "slug": "open-source",
          "color": "#3B82F6",
          "text_color": "#FFFFFF",
          "is_active": true
        }
      ],
      "organizers": [
        { "id": 5, "name": "Acme Events", "slug": "acme-events" }
      ],
      "is_active": true,
      "is_featured": false,
      "is_no_follow": false,
      "is_claimed": false,
      "votes": 42,
      "seo_title": "React.js - A JavaScript Library for Building User Interfaces",
      "seo_description": "React makes it painless to create interactive UIs.",
      "og_image": null,
      "schema": null,
      "head_html": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "listing_url": "https://your-directify-domain.com/app/1/projects/1/edit",
      "pricing": "$0 - $100/month",
      "job_type": "Full-time"
    }
  ],
  "links": {
    "first": "https://your-directify-domain.com/api/directories/1/projects?page=1",
    "last": "https://your-directify-domain.com/api/directories/1/projects?page=5",
    "prev": null,
    "next": "https://your-directify-domain.com/api/directories/1/projects?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 100,
    "to": 100,
    "total": 450
  }
}

Get Single Listing

Retrieve a specific listing by ID.

GET /api/directories/{directory_id}/projects/{project_id}

Parameters:

directory_id (integer, required): The ID of the directory
project_id (integer, required): The ID of the listing

Response:

{
  "data": {
    "id": 1,
    "name": "React.js",
    "slug": "react-js",
    "description": "A JavaScript library for building user interfaces",
    "content": "Full content body with HTML...",
    "url": "https://reactjs.org",
    "image_url": "https://example.com/images/react.jpg",
    "logo_url": "https://example.com/logos/react.png",
    "logo_alt_text": "React.js Logo",
    "image_alt_text": "React.js Homepage",
    "additional_image_urls": ["https://example.com/gallery1.jpg"],
    "additional_images_urls": ["https://cdn.example.com/gallery1.jpg"],
    "video_url": null,
    "video_thumbnail_url": null,
    "phone_number": "+1 (555) 123-4567",
    "email": "contact@reactjs.org",
    "address": "1 Hacker Way, Menlo Park, CA",
    "latitude": 37.4847,
    "longitude": -122.1477,
    "social_links": {
      "twitter": "https://twitter.com/reactjs",
      "github": "https://github.com/facebook/react"
    },
    "categories": [
      {
        "id": 1,
        "title": "Frontend",
        "parent_title": "Web Development"
      }
    ],
    "tags": [
      {
        "id": 1,
        "title": "Open Source",
        "slug": "open-source",
        "color": "#3B82F6",
        "text_color": "#FFFFFF",
        "is_active": true
      }
    ],
    "organizers": [
      { "id": 5, "name": "Acme Events", "slug": "acme-events" }
    ],
    "is_active": true,
    "is_featured": false,
    "is_no_follow": false,
    "is_claimed": false,
    "votes": 42,
    "seo_title": "React.js - A JavaScript Library for Building User Interfaces",
    "seo_description": "React makes it painless to create interactive UIs.",
    "og_image": null,
    "schema": null,
    "head_html": null,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "listing_url": "https://your-directify-domain.com/app/1/projects/1/edit",
    "pricing": "$0 - $100/month",
    "job_type": "Full-time"
  }
}

Check Listing Exists

Check if a listing with a specific URL already exists in the directory.

POST /api/directories/{directory_id}/projects/exists

Parameters:

directory_id (integer, required): The ID of the directory

Request Body:

{
  "url": "https://example.com"
}

Response (Listing exists):

{
  "message": "Listing already exists in this directory"
}

Response (Listing doesn’t exist):

{
  "message": "Listing does not exist in this directory"
}

Create Listing

Create a new listing in the directory.

POST /api/directories/{directory_id}/projects

Parameters:

directory_id (integer, required): The ID of the directory

Request Body:

{
  "name": "Example Tool",
  "url": "https://example.com",
  "description": "A great tool for developers",
  "content": "<p>Full HTML content for the listing page...</p>",
  "phone_number": "+1 (555) 123-4567",
  "email": "contact@example.com",
  "address": "123 Main St, New York, NY 10001",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "social_links": {
    "twitter": "https://twitter.com/example",
    "linkedin": "https://linkedin.com/company/example"
  },
  "category_id": 1,
  "categories": [1, 2],
  "tags": [1, 3],
  "organizers": [5, 8],
  "image_url": "https://example.com/cover.jpg",
  "logo_url": "https://example.com/logo.png",
  "additional_image_urls": [
    "https://example.com/gallery1.jpg",
    "https://example.com/gallery2.jpg"
  ],
  "video_url": "https://youtube.com/embed/abc123",
  "video_thumbnail_url": "https://example.com/video-thumb.jpg",
  "starts_at": "2026-08-01 09:00:00",
  "ends_at": "2026-09-01 09:00:00",
  "seo_title": "Example Tool - Best Developer Tool",
  "seo_description": "The leading tool for developers worldwide.",
  "head_html": "<link rel=\"alternate\" hreflang=\"es\" href=\"https://es.example.com/listings/example-tool\">",
  "is_active": true,
  "is_featured": false,
  "is_no_follow": false,
  "pricing": "Free",
  "job_type": "Full-time"
}

Linking organizers: Pass organizers as an array of organizer IDs to associate the listing with one or more organizers (agencies, studios, event hosts, etc.). Only organizers belonging to the same directory are linked — any IDs from another directory are silently ignored. Fetch available IDs with GET /api/directories/{directory_id}/organizers.

Expiring listings: starts_at and ends_at control when a listing is visible. A listing with a starts_at in the future stays hidden until that moment, and once ends_at passes it is either badged as expired or hidden entirely — depending on the directory’s expiring listings setting. Both are optional; omit them and the listing is live immediately and never expires. Accepts any date format PHP can parse, e.g. 2026-08-01 09:00:00 or 2026-08-01T09:00:00Z.

Response:

{
  "data": {
    "id": 123,
    "name": "Example Tool",
    "slug": "example-tool",
    "description": "A great tool for developers",
    "content": "<p>Full HTML content for the listing page...</p>",
    "url": "https://example.com",
    "image_url": "https://example.com/cover.jpg",
    "logo_url": "https://example.com/logo.png",
    "logo_alt_text": null,
    "image_alt_text": null,
    "additional_image_urls": ["https://example.com/gallery1.jpg", "https://example.com/gallery2.jpg"],
    "additional_images_urls": ["https://example.com/gallery1.jpg", "https://example.com/gallery2.jpg"],
    "video_url": null,
    "video_thumbnail_url": null,
    "phone_number": "+1 (555) 123-4567",
    "email": "contact@example.com",
    "address": "123 Main St, New York, NY 10001",
    "latitude": 40.7128,
    "longitude": -74.006,
    "social_links": {
      "twitter": "https://twitter.com/example",
      "linkedin": "https://linkedin.com/company/example"
    },
    "categories": [
      {
        "id": 1,
        "title": "Web Development",
        "parent_title": null
      },
      {
        "id": 2,
        "title": "Frontend",
        "parent_title": "Web Development"
      }
    ],
    "tags": [
      {
        "id": 1,
        "title": "Open Source",
        "slug": "open-source",
        "color": "#3B82F6",
        "text_color": "#FFFFFF",
        "is_active": true
      },
      {
        "id": 3,
        "title": "Free Tier",
        "slug": "free-tier",
        "color": "#10B981",
        "text_color": "#FFFFFF",
        "is_active": true
      }
    ],
    "organizers": [
      { "id": 5, "name": "Acme Events", "slug": "acme-events" },
      { "id": 8, "name": "Downtown Collective", "slug": "downtown-collective" }
    ],
    "is_active": true,
    "is_featured": false,
    "is_no_follow": false,
    "is_claimed": false,
    "votes": 0,
    "seo_title": "Example Tool - Best Developer Tool",
    "seo_description": "The leading tool for developers worldwide.",
    "og_image": null,
    "schema": null,
    "head_html": null,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "listing_url": "https://your-directify-domain.com/app/1/projects/123/edit",
    "pricing": "Free",
    "job_type": "Full-time"
  }
}

Bulk Create Listings

Create multiple listings in a single request. Up to 100 listings can be created at once. Each listing is processed independently, so if one fails, the others will still be created.

POST /api/directories/{directory_id}/projects/bulk

Parameters:

directory_id (integer, required): The ID of the directory

Request Body:

{
  "listings": [
    {
      "name": "Listing 1",
      "description": "Description for listing 1",
      "url": "https://example1.com",
      "categories": [1, 2],
      "tags": [1],
      "organizers": [5],
      "is_active": true
    },
    {
      "name": "Listing 2",
      "description": "Description for listing 2",
      "category_id": 3,
      "is_featured": true
    },
    {
      "name": "Listing 3",
      "description": "Description for listing 3",
      "url": "https://example3.com",
      "email": "contact@example3.com",
      "phone_number": "+1234567890",
      "address": "123 Main St"
    }
  ]
}

Available fields per listing:

Field	Type	Description
`name`	string, required	The listing name
`slug`	string	URL slug (auto-generated from name if omitted)
`description`	string	Short description
`content`	string	Full content/body (HTML supported)
`url`	string	Website URL (used for duplicate detection)
`phone_number`	string	Phone number
`email`	string	Contact email
`address`	string	Physical address
`latitude`	float	Map latitude coordinate
`longitude`	float	Map longitude coordinate
`social_links`	object	Social media links (e.g., `{"twitter": "...", "linkedin": "..."}`)
`category_id`	integer	Single category ID
`categories`	array	Array of category IDs
`tags`	array	Array of tag IDs
`organizers`	array	Array of organizer IDs to link (must belong to the same directory; out-of-directory IDs are ignored)
`is_active`	boolean	Published status (default: true)
`is_featured`	boolean	Featured flag
`is_no_follow`	boolean	NoFollow flag
`logo_url`	string	Logo image URL
`image_url`	string	Cover image URL
`logo_alt_text`	string	Logo alt text
`image_alt_text`	string	Cover image alt text
`additional_image_urls`	array	Gallery images hosted elsewhere, as an array of URLs. This is the writable one
`video_url`	string	Video URL
`video_thumbnail_url`	string	Video thumbnail URL
`votes`	integer	Vote count
`starts_at`	datetime	When the listing goes live. Hidden until then; omit to publish immediately
`ends_at`	datetime	When the listing expires. Badged as expired or hidden afterwards (per directory setting); omit for no expiry
`seo_title`	string	SEO meta title
`seo_description`	string	SEO meta description
`schema`	string	JSON-LD schema markup
`head_html`	string	Custom HTML for the page `<head>` section (e.g. hreflang tags)

Custom field values can also be passed by using the custom field name as the key (e.g., "pricing": "Free", "founded_year": "2020").

additional_image_urls vs additional_images_urls — these differ by a single letter and are not the same thing:

additional_image_urls (image, singular) is the writable field. Send gallery images hosted elsewhere as an array of URLs.
additional_images_urls (images, plural) is read-only, and appears in responses only. It is the listing’s complete gallery: images uploaded through the dashboard (returned as CDN URLs) followed by everything in additional_image_urls.

Read additional_images_urls when you want to render the gallery. Write additional_image_urls when you want to change it. Sending additional_images_urls does nothing.

When a url is provided, the API uses it for duplicate detection. If a listing with the same URL already exists in the directory, it will be returned as-is instead of creating a duplicate.

Response (201 Created):

{
  "data": [
    {
      "id": 123,
      "name": "Listing 1",
      "slug": "listing-1",
      "description": "Description for listing 1",
      "url": "https://example1.com",
      "is_active": true,
      "is_featured": false,
      "categories": [
        { "id": 1, "title": "Category A", "parent_title": null }
      ],
      "tags": [
        { "id": 1, "title": "Tag 1", "slug": "tag-1" }
      ],
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    {
      "id": 124,
      "name": "Listing 2",
      "slug": "listing-2",
      "description": "Description for listing 2",
      "is_active": true,
      "is_featured": true,
      "categories": [
        { "id": 3, "title": "Category C", "parent_title": null }
      ],
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "errors": [],
  "total_created": 2,
  "total_errors": 0
}

Response with partial errors:

{
  "data": [
    {
      "id": 123,
      "name": "Listing 1",
      "slug": "listing-1"
    }
  ],
  "errors": [
    {
      "index": 1,
      "name": "Listing 2",
      "error": "Error description"
    }
  ],
  "total_created": 1,
  "total_errors": 1
}

Update Listing

Update an existing listing.

PUT /api/directories/{directory_id}/projects/{project_id}

Parameters:

directory_id (integer, required): The ID of the directory
project_id (integer, required): The ID of the listing

Request Body:

{
  "name": "Updated Example Tool",
  "description": "An updated description for the tool",
  "phone_number": "+1 (555) 987-6543",
  "email": "new@example.com",
  "address": "456 Oak Ave, San Francisco, CA",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "social_links": {
    "twitter": "https://twitter.com/updated",
    "github": "https://github.com/updated"
  },
  "categories": [1],
  "tags": [1],
  "organizers": [5],
  "starts_at": "2026-08-01 09:00:00",
  "ends_at": "2026-09-01 09:00:00",
  "seo_title": "Updated Example Tool - Now Even Better",
  "seo_description": "The updated leading tool for developers.",
  "is_active": true,
  "is_featured": true,
  "pricing": "Free - $50/month"
}

Pass ends_at: null to remove an expiry date and make a listing permanent again.

Response:

{
  "data": {
    "id": 123,
    "name": "Updated Example Tool",
    "slug": "updated-example-tool",
    "description": "An updated description for the tool",
    "content": null,
    "url": "https://example.com",
    "image_url": "https://example.com/images/updated.jpg",
    "logo_url": "https://example.com/logos/updated.png",
    "logo_alt_text": null,
    "image_alt_text": null,
    "additional_image_urls": [],
    "additional_images_urls": [],
    "video_url": null,
    "video_thumbnail_url": null,
    "phone_number": "+1 (555) 987-6543",
    "email": "new@example.com",
    "address": "456 Oak Ave, San Francisco, CA",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "social_links": {
      "twitter": "https://twitter.com/updated",
      "github": "https://github.com/updated"
    },
    "categories": [
      {
        "id": 1,
        "title": "Web Development",
        "parent_title": null
      }
    ],
    "tags": [
      {
        "id": 1,
        "title": "Open Source",
        "slug": "open-source",
        "color": "#3B82F6",
        "text_color": "#FFFFFF",
        "is_active": true
      }
    ],
    "organizers": [
      { "id": 5, "name": "Acme Events", "slug": "acme-events" }
    ],
    "is_active": true,
    "is_featured": true,
    "is_no_follow": false,
    "is_claimed": false,
    "votes": 42,
    "seo_title": "Updated Example Tool - Now Even Better",
    "seo_description": "The updated leading tool for developers.",
    "og_image": null,
    "schema": null,
    "head_html": null,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T11:45:00.000000Z",
    "listing_url": "https://your-directify-domain.com/app/1/projects/123/edit",
    "pricing": "Free - $50/month"
  }
}

Partial updates: When updating a listing, you only need to send the fields you want to change. Fields that are omitted from the request body will remain unchanged. Importantly, if you omit categories, tags, or organizers from a PUT request, the existing assignments will be preserved. To explicitly clear them, send empty arrays: "categories": [], "tags": [], or "organizers": [].

Delete Listing

Delete a listing from the directory.

DELETE /api/directories/{directory_id}/projects/{project_id}

Parameters:

directory_id (integer, required): The ID of the directory
project_id (integer, required): The ID of the listing

Response:

{
  "message": "Project deleted successfully"
}

Get Started

Directories

Listings

Categories

Integrations

Ads

Forms

Settings

Paid Submissions

Blog

Content

Custom Pages/Links

AI & Automation

API

Listings

Listings

Get Directory Listings

Get Single Listing

Check Listing Exists

Create Listing

Bulk Create Listings

Update Listing

Delete Listing

​Listings

​Get Directory Listings

​Get Single Listing

​Check Listing Exists

​Create Listing

​Bulk Create Listings

​Update Listing

​Delete Listing

Listings

Get Directory Listings

Get Single Listing

Check Listing Exists

Create Listing

Bulk Create Listings

Update Listing

Delete Listing