Skip to main content

​
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
        }
      ],
      "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
      }
    ],
    "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],
  "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"
  ],
  "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,
  "pricing": "Free",
  "job_type": "Full-time"
}
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
      }
    ],
    "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],
      "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:
FieldTypeDescription
namestring, requiredThe listing name
slugstringURL slug (auto-generated from name if omitted)
descriptionstringShort description
contentstringFull content/body (HTML supported)
urlstringWebsite URL (used for duplicate detection)
phone_numberstringPhone number
emailstringContact email
addressstringPhysical address
latitudefloatMap latitude coordinate
longitudefloatMap longitude coordinate
social_linksobjectSocial media links (e.g., {"twitter": "...", "linkedin": "..."})
category_idintegerSingle category ID
categoriesarrayArray of category IDs
tagsarrayArray of tag IDs
is_activebooleanPublished status (default: true)
is_featuredbooleanFeatured flag
is_no_followbooleanNoFollow flag
logo_urlstringLogo image URL
image_urlstringCover image URL
logo_alt_textstringLogo alt text
image_alt_textstringCover image alt text
additional_image_urlsarrayArray of gallery image URLs
video_urlstringVideo URL
video_thumbnail_urlstringVideo thumbnail URL
votesintegerVote count
seo_titlestringSEO meta title
seo_descriptionstringSEO meta description
schemastringJSON-LD schema markup
head_htmlstringCustom 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").
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],
  "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"
}
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
      }
    ],
    "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 and tags from a PUT request, the existing category and tag assignments will be preserved. To explicitly clear them, send empty arrays: "categories": [] or "tags": [].

​
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"
}