API Reference

The Flashy API is a REST API served at:

Base URLhttps://api.flashy.app

Resource-oriented URLs, JSON request bodies and JSON responses. Before you can use the API, you must verify your Flashy account.

Authentication

Your account API key must be included in every request you send to the Flashy API. You can send it in a few ways — choose the best one for you:

  • As a request header named x-api-key — most recommended.
  • On GET requests, as the query parameter key=your_account_key.
  • On requests with a body, as a key property in the request body.
curl https://api.flashy.app/account \
  -H "x-api-key: YOUR_API_KEY"

You can find your API key in your Flashy dashboard under account settings.

The response envelope

Every response is JSON with the same envelope: success tells you whether the call worked, and data carries the result (or null for write operations that return nothing).

{
    "success": true,
    "data": {
        "id": 83,
        "account": "r33piu",
        "name": "My Account"
    }
}

SDKs

Every endpoint below shows the equivalent call for our SDKs where one exists:

  • PHP — the PHP SDK wraps the REST API with your API key.
  • JS SDK — the website pixel runs in the visitor's browser and covers contacts and events. It identifies the visitor for you; no API key is involved.
Resource

Account

Read & manage your Flashy account information.

Endpoints

Get the current account

GET /account
Request 
curl "https://api.flashy.app/account" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

$account = $flashy->account->get();
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 The current account. 
{
    "success": true,
    "data": {
        "id": 83,
        "account": "r33piu",
        "name": "My Account",
        "country": null,
        "website": "https://flashyapp.com",
        "phone": "972526845430",
        "credits": "24.0000",
        "created_at": 1615565991,
        "updated_at": 1631588013,
        "timezone": "America/New_York",
        "currency": "USD"
    }
}
Resource

Contacts

Contacts are the foundation of the Flashy platform. You can create them based on any unique key that you prefer, with email being the default primary key.

We created a list of properties you can use to segment your contacts, and you can always create custom properties using our dashboard — read more about Contact Properties.

Endpoints

Create (or upsert) a contact

POST /contact

Create or update contacts on Flashy by using the overwrite parameter.

Be sure to use the right primary key — our default is email address, but you can use any key you wish.

You can add a contact to a specific list using the lists object: the key is the List ID and the value is true if the customer is marketing-eligible.

Body parameters

  • primary_key string required
    Name of the primary key
  • overwrite boolean
    Update the contact if it exists
  • contact object required
    The contact object. Besides the documented properties, any custom contact property created in your dashboard can be set as an additional key.
  • contact.email string (email)
  • contact.first_name string
  • contact.last_name string
  • contact.phone string
  • contact.birthday integer
    Unix timestamp
  • contact.source string
  • contact.lists object
    Key is the List ID; value is true if the contact is marketing-eligible for that list.
Request 
curl -X POST "https://api.flashy.app/contact" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_key": "email",
    "overwrite": false,
    "contact": {
        "email": "user1@name.com",
        "first_name": "Rafael",
        "last_name": "Mor",
        "lists": {
            "159": true,
            "170": false
        },
        "birthday": 1631631569
    }
}'
Send your API key in the x-api-key header. Authentication 
// Runs in the visitor's browser once the base pixel is installed — no API key.
// The second argument is an optional list ID to subscribe the contact to.
flashy.contacts.create({
    email: 'user1@name.com',
    first_name: 'Rafael',
    last_name: 'Mor',
}, 159);

// Create or update (the REST `overwrite: true`):
flashy.contacts.createOrUpdate({ email: 'user1@name.com', first_name: 'Rafael' }, 159);
Runs in the visitor’s browser through the website pixel — no API key. Install the pixel 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

// create($contact, $primary_key = 'email', $tracking = true, $overwrite = null)
// Pass true as the last argument to update the contact if it already exists.
$flashy->contacts->create([
    'email' => 'user1@name.com',
    'first_name' => 'Rafael',
    'last_name' => 'Mor',
    'lists' => ['159' => true, '170' => false],
    'birthday' => 1631631569,
], 'email', true, false);
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 The created contact. 
{
    "success": true,
    "data": {
        "email": "user1@name.com",
        "first_name": "Rafael",
        "last_name": "Mor",
        "birthday": 1631631569,
        "created_at": 1631631588,
        "contact_id": "2291112565587e24668e171940cab7cc",
        "lists": {}
    }
}

Get a contact

GET /contact/{identifier}

Use your primary key to find a contact — e.g. GET /contact/user1@name.com?primary_key=email or GET /contact/1a6711a68d0c381013ab72d3320ba4e5?primary_key=contact_id.

Path parameters

  • identifier string required
    The contact identifier (the value of the primary key, e.g. the email address or contact_id).

Query parameters

  • primary_key string default: email
    The primary key to look the contact up by. Default is email.
Request 
curl "https://api.flashy.app/contact/user1@name.com?primary_key=email" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication 
// get(identifier, primary_key = 'email')
flashy.contacts.get('user1@name.com', 'email').then(({ data }) => {
    console.log(data);
});
Runs in the visitor’s browser through the website pixel — no API key. Install the pixel 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

// get($identifier, $primary_key = 'email')
$contact = $flashy->contacts->get('user1@name.com', 'email');
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 The contact. 
{
    "success": true,
    "data": {
        "contact_id": "1a6711a68d0c381013ab72d3320ba4e5",
        "email": "user1@name.com",
        "birthday": 1631631569,
        "created_at": 1632022656,
        "phone": "",
        "first_name": "Rafael",
        "last_name": "Mor",
        "lists": {}
    }
}

Update a contact

PUT /contact/{identifier}

Update contact properties by the contact primary key.

Note that the contact's primary-key value must be part of the endpoint URL to find the contact. The primary key itself can't be updated.

Path parameters

  • identifier string required
    The contact identifier (the value of the primary key, e.g. the email address or contact_id).

Query parameters

  • primary_key string default: email
    The primary key to look the contact up by. Default is email.

Body parameters

  • contact object required
    The contact object. Besides the documented properties, any custom contact property created in your dashboard can be set as an additional key.
  • contact.email string (email)
  • contact.first_name string
  • contact.last_name string
  • contact.phone string
  • contact.birthday integer
    Unix timestamp
  • contact.source string
  • contact.lists object
    Key is the List ID; value is true if the contact is marketing-eligible for that list.
Request 
curl -X PUT "https://api.flashy.app/contact/user1@name.com?primary_key=email" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
        "last_name": "Mor",
        "source": "Google",
        "lists": {
            "159": true
        }
    }
}'
Send your API key in the x-api-key header. Authentication 
// Updates the contact currently identified in this browser
// (after flashy.contacts.create() or flashy('setCustomer', ...)).
flashy.contacts.update({
    last_name: 'Mor',
    source: 'Google',
});
Runs in the visitor’s browser through the website pixel — no API key. Install the pixel 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

// update($contact, $primary_key = 'email') — the contact array must include
// the primary-key value (here: email) so the SDK knows which contact to update.
$flashy->contacts->update([
    'email' => 'user1@name.com',
    'last_name' => 'Mor',
    'source' => 'Google',
    'lists' => ['159' => true],
], 'email');
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 The updated contact. 
{
    "success": true,
    "data": {
        "contact_id": "1a6711a68d0c381013ab72d3320ba4e5",
        "email": "user1@name.com",
        "birthday": 1631631569,
        "created_at": 1632022656,
        "phone": "",
        "first_name": "Rafael",
        "last_name": "Mor",
        "source": "Google",
        "lists": {}
    }
}

Block a contact

POST /contact/{identifier}/block

Mark a contact as blocked whenever you don't want them to receive Flashy emails and SMS messages. The platform will mark them as unsubscribed on all mailing lists they are a member of.

The contact can sign up again and the status will change to subscribed based on the list they signed up for.

Path parameters

  • identifier string required
    The contact identifier (the value of the primary key).

Query parameters

  • primary_key string default: email
    The primary key to look the contact up by. Default is email.
Request 
curl -X POST "https://api.flashy.app/contact/user1@name.com/block?primary_key=email" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

// block($identifier, $primary_key = 'email')
$flashy->contacts->block('user1@name.com', 'email');
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 Contact blocked. 
{
    "success": true,
    "data": null
}
Resource

Lists

Manage your newsletter lists.

Endpoints

Get all lists

GET /lists

Get all the lists of the account.

If you need to subscribe a contact to a list, see Contact Create / Update.

Request 
curl "https://api.flashy.app/lists" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

$lists = $flashy->lists->get();
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 All lists of the account. 
{
    "success": true,
    "data": [
        {
            "id": 4,
            "title": "First List",
            "updated_at": 1617091503
        },
        {
            "id": 5,
            "title": "Second List",
            "updated_at": 1617091621
        }
    ]
}
Resource

Messages

Flashy is an omnichannel platform that lets you send email, SMS and push notifications. Utilize our API to communicate with your customers via the channel that you choose.

Endpoints

Send an email

POST /messages/email

Using our Drag & Drop editor, you can design and maintain your email templates, and pass the template ID in the API to send beautiful responsive email templates.

As an alternative to using one of your email templates, you can pass the HTML as part of the request — set either html or template on the message.

Body parameters

  • message object required
  • message.html string
    Raw HTML of the email. Use this or template.
  • message.template string
    Template ID designed in the Flashy editor. Use this or html.
  • message.subject string required
  • message.from object required
  • message.from.name string required
  • message.from.email string (email) required
  • message.to object required
  • message.to.name string required
  • message.to.email string (email) required
  • message.vars object
    Any key/value variables to use inside the template.
Request 
curl -X POST "https://api.flashy.app/messages/email" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
        "html": "<html><head><title>Email Page Title</title></head><body><h1>Hello World!</h1><p>Sent from Flashyapp.</p></body></html>",
        "subject": "Anything",
        "from": {
            "name": "Flashy API Test",
            "email": "dev@flashyapp.com"
        },
        "to": {
            "name": "Test User",
            "email": "hello@flashyapp.com"
        },
        "vars": {
            "unique_hash": "somethinghere"
        }
    }
}'
Send your API key in the x-api-key header. Authentication 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

$flashy->messages->email([
    'html' => '<html><head><title>Email Page Title</title></head><body><h1>Hello World!</h1><p>Sent from Flashyapp.</p></body></html>',
    'subject' => 'Anything',
    'from' => ['name' => 'Flashy API Test', 'email' => 'dev@flashyapp.com'],
    'to' => ['name' => 'Test User', 'email' => 'hello@flashyapp.com'],
    'vars' => ['unique_hash' => 'somethinghere'],
]);
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 Email queued for delivery. 
{
    "success": true,
    "data": null
}

Send an SMS

POST /messages/sms

SMS messages can be sent worldwide through the Flashy platform. Make sure you include the country prefix on the phone number — for example, a United Kingdom number must include the 44 country code (list of country codes).

You must have credits on your account in order to send SMS messages.

Body parameters

  • message object required
  • message.from string required
    Sender name or number
  • message.to string required
    Recipient phone number, incl. country code
  • message.message string required
  • message.transactional boolean default: false
Request 
curl -X POST "https://api.flashy.app/messages/sms" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
        "from": "Flashyapp",
        "to": "972526845430",
        "message": "Hello World!",
        "transactional": false
    }
}'
Send your API key in the x-api-key header. Authentication 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

$flashy->messages->sms([
    'from' => 'Flashyapp',
    'to' => '972526845430',
    'message' => 'Hello World!',
    'transactional' => false,
]);
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 SMS queued for delivery. 
{
    "success": true,
    "data": null
}
Resource

Search

Search contacts.

Endpoints

Search contacts

GET /search

Search contacts using a phone number or email address. If searching by phone, exclude the + sign and enter the number with the international prefix.

Query parameters

  • type string required default: contacts
    The default is contacts.
  • query string required
    The email address or phone number of the contact you are looking for.
Request 
curl "https://api.flashy.app/search?type=contacts&query=user@name.com" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Matching contacts. 
{
    "success": true,
    "data": {
        "results": [
            {
                "contact_id": "ffbed8733ed83e70bc88910d6de71ef0",
                "email": "user@name.com",
                "phone": "972526845999",
                "created_at": 1631625209
            }
        ],
        "total": 1
    }
}
Resource

Events

The Events resource contains endpoints related to the tracking and management of user interactions within our marketing automation platform. Events are pivotal in triggering automations and collecting data about contact activities. These events can be generated both from online and offline interactions, enabling a comprehensive tracking system. Online events typically originate from digital interactions, while offline events are sourced from non-digital or physical world interactions.

Endpoints

Send an event

POST /event

Send events to keep track of your contacts' activity and start automations based on them.

You can read about all the event types we support in the Events guide. There is always an option to use a Custom Event, but we suggest using our pre-defined events when they exist.

Body parameters

  • event string required
    Event name (e.g. ViewContent, AddToCart, Purchase, UpdateCart, CustomEvent).
  • body object required
    Event payload — see the Events guide for the shape of each event type.
Request 
curl -X POST "https://api.flashy.app/event" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "ViewContent",
    "body": {
        "email": "contact@company.com",
        "content_ids": [
            "38",
            "789"
        ]
    }
}'
Send your API key in the x-api-key header. Authentication 
// The pixel attaches the visitor's identity for you — send the event body only.
flashy('ViewContent', {
    content_ids: ['38', '789']
});
Runs in the visitor’s browser through the website pixel — no API key. Install the pixel 
$flashy = new Flashy\Flashy(['api_key' => 'YOUR_API_KEY']);

// track($event, $params) — $params must identify the contact (email, contact_id or flashy_id)
$flashy->events->track('ViewContent', [
    'email' => 'contact@company.com',
    'content_ids' => ['38', '789'],
]);
composer require flashy/flashy-php PHP SDK setup
has no method for this endpoint — showing REST.
Response 200 Event accepted. 
{
    "success": true,
    "data": null
}

Send an offline event

POST /event/offline

Send events from offline sources. The main difference here is the fallback on the contact primary key — first we look the contact up by email, and if not found we look by phone. Make sure to send both keys you have, for a better match.

This endpoint is available on the Master plan and above.

Make sure to use the country code if you include a phone number (list of country codes).

Request 
curl -X POST "https://api.flashy.app/event/offline" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase",
    "body": {
        "order_id": "159",
        "value": 150,
        "currency": "USD",
        "phone": "972526845400",
        "email": "contact@company.com",
        "content_ids": [
            "38",
            "789"
        ],
        "channel": "offline",
        "branch": "San Francisco"
    }
}'
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Event accepted. 
{
    "success": true,
    "data": null
}
Resource

Reports

Campaign and automation performance reports.

Endpoints

Email campaign reports

GET /reports/emails

Retrieve detailed reports for all sent email campaigns within a specified date range. Provides comprehensive statistics and performance metrics for campaigns sent during the defined period.

Query parameters

  • from integer required
    Unix timestamp after campaign is sent
  • to integer required
    Unix timestamp before campaign is sent
Request 
curl "https://api.flashy.app/reports/emails?from=1640995200&to=1643673600" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Campaign reports. 
{
    "success": true,
    "data": [
        {
            "campaign_id": 24,
            "campaign_name": "Any Campaign Title",
            "subject_line": "The campaign subject line",
            "sent_date": "2021-12-29",
            "sent_time": "06:27:11",
            "day_of_week": "Wednesday",
            "total_recipients": 300,
            "total_delivered": 300,
            "delivery_rate": "100%",
            "total_opens": 0,
            "open_rate": "0%",
            "unique_clicks": 0,
            "total_clicks": 10,
            "click_through_rate_ctr": "0%",
            "purchases": 0,
            "conversion_rate": "0%",
            "revenue_generated": "$0.00",
            "avg_purchase_value": "$0.00",
            "revenue_per_message": "$0.00",
            "total_bounces": 0,
            "soft_bounces": 0,
            "hard_bounces": 0,
            "bounce_rate": "0%",
            "unsubscribed": 0,
            "unsubscribe_rate": "0%",
            "total_spam": 0,
            "spam_rate": "0%"
        }
    ]
}

SMS campaign reports

GET /reports/sms

Retrieve detailed reports for all sent SMS campaigns within a specified date range.

Query parameters

  • from integer required
    Unix timestamp after campaign is sent
  • to integer required
    Unix timestamp before campaign is sent
Request 
curl "https://api.flashy.app/reports/sms?from=1640995200&to=1643673600" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Campaign reports. 
{
    "success": true,
    "data": [
        {
            "campaign_id": 72,
            "campaign_name": "Campaign Title",
            "sent_date": "2022-05-30",
            "sent_time": "09:10:32",
            "day_of_week": "Monday",
            "total_recipients": 100,
            "total_delivered": 100,
            "delivery_rate": "100%",
            "unique_clicks": 1,
            "total_clicks": 1,
            "click_through_rate_ctr": "1.00%",
            "purchases": 0,
            "conversion_rate": "0%",
            "revenue_generated": "$0.00",
            "avg_purchase_value": "$0.00",
            "revenue_per_message": "$0.00",
            "failed_rate": "0%",
            "unsubscribed": 0,
            "unsubscribe_rate": "0%"
        }
    ]
}

Automation reports

GET /reports/automations

Retrieve detailed reports for all automations executed within a specified date range, with a maximum allowed timespan of 31 days. The data is broken down by automation and date, allowing day-by-day performance metrics per automation.

Query parameters

  • from integer required
    Unix timestamp of starting the automation
  • to integer required
    Unix timestamp of completing the automation
Request 
curl "https://api.flashy.app/reports/automations?from=1640995200&to=1643673600" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Automation reports, broken down by automation and date.
Resource

Webhooks

The Webhooks resource enables users to set up custom webhooks that are triggered by specific events on our platform. This feature allows users to receive real-time notifications to a specified URL when designated events occur. It enhances integration capabilities, allowing for automated reactions in external systems or applications in response to activities within our platform.

See the Webhooks guide for every event payload and how deliveries work.

Endpoints

List configured webhooks

GET /webhooks

Retrieve a list of all webhooks configured for a specific account. This endpoint provides an overview of active webhooks, including their URLs and the events they are set to listen to. It's useful for managing and reviewing webhook configurations.

Request 
curl "https://api.flashy.app/webhooks" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Configured webhooks.

List available webhook events

GET /webhooks/list

Fetch the list of events that webhooks can listen to (such as contact_created, email_campaign_opened). Use it for planning and setting up new webhooks.

Request 
curl "https://api.flashy.app/webhooks/list" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Available webhook event names.

Create a webhook

POST /webhook

Create a new webhook. Specify the URL where notifications should be sent and the events to monitor. See the Webhooks guide for every payload you will receive.

Body parameters

  • endpoint string (uri) required
  • events array of string required
Request 
curl -X POST "https://api.flashy.app/webhook" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://mydomain.com/",
    "events": [
        "contact_created",
        "email_campaign_opened"
    ]
}'
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Webhook created.

Update a webhook

PUT /webhook

Modify the list of events a webhook listens to or change its destination URL.

Request 
curl -X PUT "https://api.flashy.app/webhook" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Webhook updated.

Delete a webhook

DELETE /webhook

Permanently delete a specified webhook and stop all its event notifications.

Request 
curl -X DELETE "https://api.flashy.app/webhook" \
  -H "x-api-key: YOUR_API_KEY"
Send your API key in the x-api-key header. Authentication
has no method for this endpoint — showing REST.
Response 200 Webhook deleted.