Overview

Welcome to the profileAPI Developers Reference. This documentation portal is your guide to understanding and utilizing our API's full capabilities.

About

Overview

This section outlines the general guidelines and naming conventions used across our API documentation. It aims to provide clarity and consistency in how we present our APIs to ensure they are easily understandable and usable for developers.

Documentation Structure

Our API documentation is organized into distinct sections to ensure comprehensive coverage and ease of navigation:

• Common (This Page): Addresses universal aspects relevant to all API interactions, including authentication procedures, pagination mechanics, and rate-limiting guidelines.
• APIs (Version YYYY-MM-DD): Dedicated to a specific version of the API, further divided into:
  • Data Types: Outlines custom data types that are integral to the APIs and their corresponding object models.
  • Object Models: Provides detailed descriptions of the resources manipulated or accessed through the APIs.
  • API: Explores the various operations that can be performed on resources, complete with parameters, request and response structures, and practical usage examples.

Naming and Formatting Conventions

To ensure consistency and predictability throughout our API, we adhere to specific naming and formatting conventions:

• CamelCase for Requests and Responses: We use CamelCase to name API requests and responses. For abbreviations, only the first letter is capitalized (e.g., linkedInUrl instead of linkedInURL).
• CamelCase for Keys: Keys within JSON objects are in camelCase (e.g., "businessModels").
• Kebab Case for URLs: For endpoint URLs and links to external resources, we use kebab-case (e.g., https://api.example.com/company-filter-categories).

Query parameters in URLs (after ?) follow camelCase and are case-sensitive, e.g., https://api.example.com/kebab-case-resource?caseSensitiveQueryParameter=value1.

• UUIDs as Strings: Identifiers such as personId or companyId are formatted as strings (e.g., "9e6a55b258ef11edb8780242ac120002").
• Capitalization for Names: Names within the API are typically capitalized for the first word (e.g., { "type": "Business Models" }).
• ISO 8601 for Dates and Times: Dates and times follow the ISO 8601 standard. Datetimes include the time value (2020-08-12T02:12:33.231Z), while dates are presented as just the date (2020-08-12).
• Null for Absent Values: The API does not support empty strings. Explicitly use null instead of "" to indicate the absence of a value. Responses will include complete objects with null for non-existent values.

Example Documentation Format

The following JSON example demonstrates our conventions for identifiers, keys, names, and handling of values:

{
  "id": "9e6a55b258ef11edb8780242ac120002",
  "key": "businessModels",
  "name": "Business Models",
  "createdAt": "2020-08-12T02:12:33.231Z",
  "description": null
}

Authentication

Obtaining Your API Key

To start using our APIs, you need an API key. You can request one by booking an introductory call through our website at profileapi.com. After reviewing your request, our team will securely send you an API key.

Always store your API key in environment variables to keep it secure. Avoid including it directly in your codebase or version control systems.

Using Your API Key

Once you have received your API key, you can authenticate API requests. The key should be included in the header of each HTTP request you make to the API.

Making an API Call with Your API Key

To authenticate an API request with your API key, include it in the Authorization header as follows:

Authorization: ApiKey your_api_key_here

API Versioning

The profileAPI employs a date-based versioning system to ensure that changes and upgrades do not disrupt existing integrations. Each API version is identified by the release date in a YYYY-MM-DD format. This approach allows developers to specify the version they want to use and to adapt to new changes at their own pace. The latest API version is 2024-03-01.

URL Format

https://api.profileAPI.com/YYYY-MM-DD/{resource}

Response Structure

The profileAPI adheres to a standardized response format for all endpoints, simplifying integration and troubleshooting processes. This standardized response structure is consistent whether the API call is successful or fails, and it includes comprehensive debugging information to assist in both scenarios.

General Response Components

Each response from the profileAPI contains:

• Meta Object: Always present, it provides critical operational and debugging information.
• Data Object: Returned on successful API calls with relevant data.
• Error Object: Returned on failed API calls with error details.

Meta Object Structure

The meta object is included in every response and contains essential information for understanding the operation's outcome:

Field	Type	Description
statusCode	number	Reflects the HTTP status code, indicating the outcome of the API operation.
message	string	Provides detailed context about the operation, aiding troubleshooting efforts.
requestId	string	A unique identifier for the request, important for tracking and support purposes.

Successful Responses

Success responses vary based on the API operation but follow a consistent pattern:

Standard HTTP Status Codes for Success

statusCode	Description
200	Operation was successfully executed immediately (e.g., retrieval, update).
201	Resource was successfully created.
202	Operation accepted and is being processed asynchronously.

Data Object on Success

The data object varies based on the API but follows these patterns:

• Empty Object: Indicates that the operation has returned no specific data.
• Object with Details: Contains identifiers or detailed information when operations modify or create resources.
• Array of Objects: Used when multiple records are returned; can be empty if no records are found.

Examples of Success Responses:

For operations without specific data:

{
  "meta": {
    "statusCode": 200,
    "message": "Request processed successfully.",
    "requestId": "a73qdn12"
  },
  "data": {}
}

For creation operations:

{
  "meta": {
    "statusCode": 201,
    "message": "The user was created successfully.",
    "requestId": "a73qdn12"
  },
  "data": {
    "id": "9e6a55b258ef11edb8780242ac130003"
  }
}

For batch operations with pagination details:

{
  "meta": {
    "statusCode": 200,
    "message": "Items returned successfully.",
    "requestId": "a73qdn12"
  },
  "data": {
    "results": [ 
      { "id": "9e6a55b258ef11edb8780242ac130003" },
      { "id": "9e6a55b258eedckee3s9iej3n34455s1" }
    ],
    "pagination": {
      "nextStart": []
    }
  }
}

Error Responses

Error responses provide structured details about the issues encountered during API operations:

Standard HTTP Status Codes for Errors

StatusCode	Description
400	Invalid request parameters were provided.
401	Authentication failed due to missing or invalid API key.
402	Subscription expired, requiring renewal.
429	Rate limit exceeded, indicating too many requests.
500	Internal server errors occurred.
503	Service is unavailable due to maintenance or downtime.

Error Object on Failures

The error object may contain detailed explanations of the errors, including field-specific messages or resolution suggestions.

Example of an Error Response:

For operations without specific error:

{
  "meta": {
    "statusCode": 503,
    "message": "Service temporarily unavailable due to server maintenance. Please try again later.",
    "requestId": "a73qdn12"
  },
  "error": {}
}

For authentication errors:

{
  "meta": {
    "statusCode": 401,
    "message": "Authentication failed. API key missing or invalid.",
    "requestId": "a73qdn12"
  },
  "error": {
    "resolution": "Verify and provide a valid API key."
  }
}

For validation errors with multiple details:

{
  "meta": {
    "statusCode": 400,
    "message": "Validation errors occurred.",
    "requestId": "a73qdn12"
  },
  "error": {
    "errors": [
      {"field": "email", "message": "Email is required and cannot be empty."},
      {"field": "password", "message": "Password must be at least 8 characters long."}
    ]
  }
}

Rate Limiting

Understanding and managing rate limits is essential for optimizing your interactions with our API. We provide rate-limiting information via HTTP headers and relevant status codes with every response. This helps your applications adjust dynamically to our usage policies and subscription tier. It's important to note that rate limiting may vary from one API endpoint to another.

Rate Limit Headers

To help your application manage its request frequency effectively, our API includes detailed information about your current rate limit status in the headers of each response. These headers allow you to proactively adjust your request rates before reaching the rate limit ceiling.

X-RateLimit-Limit

• Type: Integer
• Description: Indicates the maximum number of requests your application can make within the designated time window.

X-RateLimit-Remaining

• Type: Integer
• Description: Shows the number of requests left for your API key in the current rate limit window, helping you gauge when to slow down your request pace.

X-RateLimit-Reset

• Type: Timestamp (UTC epoch seconds)
• Description: The exact time when the rate limit will reset to its maximum capacity. This timestamp is crucial for appropriately scheduling subsequent requests.

Example of Rate Limit Headers in a Response

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Handling Rate Limits

While our API provides proactive rate limit information, your application should implement logic to respect these limits. Check the headers in each response and adjust your request patterns accordingly.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 120
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459200
{
  "message": "Rate limit exceeded. Try again in 120 seconds."
}

Pagination

Our API employs cursor-based pagination, an effective method to manage large datasets by fetching records in segments. This approach relies on a cursor token (nextStart) that points to the start of the next page of results.

Pagination Structure

Responses for paginated endpoints are structured to include both metadata and data objects:

• meta: Contains information about the request and the status of the response.
• data: Holds the resource data and pagination details.
  • results: An array of resource objects for the current page.
  • pagination: Contains the cursor for the next page.
    • nextStart: A cursor indicating the start of the next set of results. If null, there are no more pages to retrieve.

Example Response

{
  "meta": {
    "statusCode": 200,
    "message": "Items returned successfully.",
    "requestId": "a73qdn12"
  },
  "data": {
    "results": [
      { "id": "9e6a55b258ef11edb8780242ac130003" },
      { "id": "9e6a55b258eedckee3s9iej3n34455s1" }
    ],
    "pagination": {
      "nextStart": []
    }
  }
}

Requesting Data

To navigate through the pages:

• Initial Request: Fetch the first page by calling the endpoint without a nextStart query parameter.

  GET https://api.profileapi.com/{{version}}/{{resource}}

• Subsequent Requests: To access the following pages, include the nextStart value retrieved from the previous pagination object.

  GET https://api.profileapi.com/{{version}}/{{resource}}?nextStart={{value}}

Replace nextStart token from the preceding response.

Client-Side Handling of Pagination

It's important for client applications to manage pagination dynamically:

1. Check pagination.nextStart: Determine if there is a subsequent page.
2. Use nextStart for further requests: If pagination.nextStart exists, it's used as the parameter for the next request.
3. End of Data: If pagination.nextStart is null, stop making requests as it signifies no further data is available.