Skip to main content

Quick Start Guide

This guide will walk you through making your first API calls to the DeePsy API v1. We'll cover the essential endpoints to get you up and running quickly.

Prerequisites Required

Before you start, make sure you have:

  1. Dashboard Access: You need access to deepsy.fr/dashboard
  2. API Key: Follow our Authentication Guide to create your API key
  3. Company Membership: You must be a member of at least one company

Step 1: Test Your API Key​

First API Call

Let's start with a simple health check to verify your API key is working:

curl -X GET "https://deepsy.fr/api/v1/health" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Expected Response:

{
  "status": "ok"
}

Step 2: Get Your User Information​

Retrieve your user profile and associated companies:

curl -X GET "https://deepsy.fr/api/v1/user/me" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Expected Response:

{
  "first_name": "John",
  "last_name": "Doe",
  "display_name": "John Doe",
  "email": "john.doe@example.com",
  "companies": [
    {
      "company_id": "c193a06f-1c25-4e65-84a7-95faaae7ae7b",
      "permissions": 6,
      "company": {
        "name": "Acme Corporation",
        "profile_picture": "https://example.com/logo.jpg"
      }
    }
  ]
}

Step 3: List Your Companies​

Get detailed information about all companies you have access to:

curl -X GET "https://deepsy.fr/api/v1/user/companies" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Expected Response:

{
  "items": [
    {
      "company_id": "c193a06f-1c25-4e65-84a7-95faaae7ae7b",
      "permissions": ["ADMINISTRATOR", "MANAGE_CAMPAIGN"],
      "created_at": "2023-01-01T00:00:00Z",
      "company": {
        "name": "Acme Corporation",
        "email": "contact@acme.com",
        "website": "https://acme.com",
        "industry": "Technology"
      }
    }
  ],
  "count": 1
}

Step 4: Get Company Details​

Retrieve detailed information about a specific company:

curl -X GET "https://deepsy.fr/api/v1/companies/{company_id}/get-details" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Replace {company_id} with the actual company ID from the previous response.

Step 5: List Campaigns​

If you have campaign management permissions, list campaigns for your company:

curl -X GET "https://deepsy.fr/api/v1/campaign/{company_id}/list" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

List Endpoints and Pagination​

Most list endpoints in the DeePsy API follow a consistent pattern for responses and query parameters.

Standard List Response Format​

All list endpoints return data in this format:

{
  "items": [...],  // Array of items
  "count": 25,     // Total number of items
  "pages": 3       // Total number of pages
}

Query Parameters​

List endpoints support these query parameters:

ParameterTypeDefaultDescription
pageinteger1Page number to retrieve
limitinteger10Number of items per page (max 100)
orderstring"desc"Sort order: "asc" or "desc"
order_bystring"created_at"Field to sort by
querystring-Search query (if endpoint supports search)

Example with Query Parameters​

curl -X GET "https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/list?page=2&limit=20&order=asc&order_by=name" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"
HTTP Response Codes

Common Response Codes​

  • 200: Success
  • 401: Unauthorized (invalid API key)
  • 403: Forbidden (insufficient permissions)
  • 404: Not found
  • 422: Validation error
  • 500: Internal server error

Error Handling​

All errors follow a consistent format:

{
  "error": "Error description",
  "error_code": "ERROR_CODE_CONSTANT"
}

For detailed error handling, see our Error Handling Guide.

Next Steps​

Now that you've made your first API calls, explore these guides:

Need Help?​

If you encounter any issues: