Skip to main content

Overview

API reference​

The Photon API is organized around REST. Our API has predictable resource-oriented URLs and returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Photon API in sandbox mode, which is a completely different environment used for testing API integrations.

You can view all available APIs in Photon Swagger.

Authentication​

The Photon API uses API keys to authenticate requests. You can view and manage your API keys in the Photon Plus Company data page.

Sandbox API keys can be viewed here: Sandbox Photon Plus Company data.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Authorization header.
Provide your API key as "Authorization: apikey YOUR_API_KEY"

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Datetime format​

All datetime properties are strings with date-time format indicated in Swagger. date-time format should match ISO8601.

Errors​

Photon API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided ( e.g., a required parameter was omitted, the parameter was invalid etc.). Codes in the 5xx range indicate an error with Photon's servers (these are rare, we are getting notified about these).

Sometimes errors have response bodies:

{
  // Error message
  "error_message": "",
  // Error details
  "error": {}
}

Versioning​

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2023-02-09. For all API updates, view our Changelog.

All requests use the latest API version, unless you set the API version of the request. To set the API version on a specific request, send a X-Photon-ApiVersion header like "X-Photon-ApiVersion: 2023-02-09"

As a precaution, use API versioning to test a new API version before committing to an upgrade.

Curently supported API versions:

  • 2023-02-09
  • 2023-07-10

Rate limits​

The Photon API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession may see error responses that show up as status code 429.

A rate limiter limits the number of requests received by the API within any given second. Photon allows up to 30 operations per second.

Webhooks​

Photon uses webhooks to notify your application when an event happens in your account.

A webhook enables Photon to push notifications to your app. Photon uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Steps to receive webhooks​

You can start receiving event notifications in your app using the steps in this section:

  1. Identify the events you want to monitor and the event payloads to parse.
  2. Create and deploy a webhook endpoint as a publicly accessible HTTPS endpoint.
  3. Register your publicly accessible HTTPS URL in Photon Plus Company data page.
  4. Handle requests from Photon by parsing each event object and returning 2xx response status codes.
info

Test that your webhook endpoint is working properly using the sandbox environment.

How to create a webhook endpoint​

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTPS endpoint on your server with a URL. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. Photon sends events to your webhook endpoint as part of a POST request with a JSON payload.

You can view the Event object schema on the Swagger page.

{
  "id": "2Zj5zzFU3a9abcZ1aYYYaaZ1",
  "type": "project.state.updated",
  "createdAt": "2023-02-21T15:05:04.569Z",
  "apiVersion": "2023-02-09",
  "data": {
    "object": {
      ...
    },
    "previousAttributes": {
      ...
    }
  }
}

Event handling​

The structure of an Event object sent in a webhook is dictated by the latest API version at the time of the event’s occurrence. Event objects can never be changed once created.

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

We do not guarantee delivery of events in the order in which they are generated.

Events​

project.state.updated

The project state updated.

project.photographer.updated

The project photographer updated.

project.code_data.updated

One of project's code data has been updated. (e.g. project's dates, location, etc.)

Sandbox​

The Photon sandbox is a test environment where you can test your API integration. The latest api versions gets rolled out here first, so you can make changes.

The following features are not available in the sandbox environment:

  • Scheduled updates (like monthly reports)
  • Invoices
  • Google Drive connection
  • Requesting new package or package modification
  • Messaging

Please be aware, that user and contact notification emails are still being sent in the sandbox environment.

You can test webhook integrations with services like Webhook.site.

Sandbox domains:

Simulating the full project process​

You can test the whole project by simulating project state transitions. Calling the POST /sandbox/step endpoint moves your projects to the "next" state. This endpoint is only available in the sandbox environment.

Simulated project state transitions:

  1. created / on-hold
  2. started
  3. in-progress
  4. retouching
  5. delivered

Changelog​

This changelog lists all additions and updates to the Photon API, in chronological order.

July 10, 2023​

  • Replace project location from string to object with city, zipCode, address and country properties in create, modify project request
  • Added GET /packages/availableTimeSlots endpoint

February 9, 2023​

  • The initial release of the API.

Domains and IP Addresses​

Your integration must be able to reach any of Photon’s fully qualified domain names for it to function properly. Depending on how your integration operates, you may need add them to an allowlist.

To help your integration operate securely, it must also verify that it’s communicating with api.thephoton.hu through one of our listed IP addresses.

If your integration also receives webhooks from us, make sure these events originate from a Photon webhook IP address.

IP addresses​

161.156.172.87