--- source_url: https://www.pubnub.com/docs/analytics/decisions/use-external-data title: Use external data with Illuminate updated_at: 2026-09-30T07:20:08.000Z --- # Use external data with Illuminate ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. This guide shows you how to send data from an external system to PubNub Illuminate using the Fire API. ## Before you start Before starting, confirm you have: * A PubNub account with at least one app and keyset. If you do not have one, create it in the [Admin Portal](https://admin.pubnub.com/). The external system needs the publish and subscribe keys from that keyset. * [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) enabled on the keyset. This is recommended for production keysets. With Access Manager on, the external system needs a token that your server granted with `write` permission on the channel. Fire uses the publish endpoint, so it needs the same permission as [publishing](https://www.pubnub.com/docs/security/access-control/operations-permissions-mapping.md#pubsub). To grant a token, see [Grant a token](https://www.pubnub.com/docs/security/access-control/manage-permissions.md#grant-a-token). Keep the secret key on your server. A system that sends with a granted token doesn't need it. * A [Business Object](https://www.pubnub.com/docs/analytics/decisions/business-objects.md) for the channel you will fire messages to. For an overview of how external data sources work with Illuminate, see [External data sources](https://www.pubnub.com/docs/analytics/decisions/external-data-sources.md). ## Map and activate the Business Object Map and activate the Business Object before you send any data. Activation starts data capture, so Illuminate doesn't capture messages you fire before it. 1. Map each data field of your [Business Object](https://www.pubnub.com/docs/analytics/decisions/business-objects.md) to a JSON path in the payload you will fire. Use the same JSON path structure as for Publish API messages. The payload format is identical. 2. Activate the Business Object. For the steps, see [Create a Business Object](https://www.pubnub.com/docs/analytics/decisions/create-business-objects.md#activate). If you need help mapping your payload structure, [contact support](https://support.pubnub.com/hc/en-us/requests/new). ## Send a fire request Send data to Illuminate by firing a message to a channel on your keyset. Choose an SDK or make a direct REST call. ### Using an SDK The Fire API is available in most PubNub SDKs. The following examples fire a `"Hello!"` message to a channel. Replace the channel name and message with your actual payload. For SDKs not shown here, [Asyncio](https://www.pubnub.com/docs/sdks/asyncio/api-reference/publish-and-subscribe.md#fire), [C#](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/publish-and-subscribe.md#fire), [Cocoa Objective-C](https://www.pubnub.com/docs/sdks/cocoa-objective-c/api-reference/publish-and-subscribe.md#fire-builder-pattern), [Cocoa Swift](https://www.pubnub.com/docs/sdks/cocoa-swift/api-reference/publish-and-subscribe.md#fire-builder-pattern), [Go](https://www.pubnub.com/docs/sdks/go/api-reference/publish-and-subscribe.md#fire), [Java](https://www.pubnub.com/docs/sdks/java/api-reference/publish-and-subscribe.md#fire), [Kotlin](https://www.pubnub.com/docs/sdks/kotlin/api-reference/publish-and-subscribe.md#fire), [Objective-C](https://www.pubnub.com/docs/sdks/objective-c/api-reference/publish-and-subscribe.md#fire-builder-pattern), [PHP](https://www.pubnub.com/docs/sdks/php/api-reference/publish-and-subscribe.md#fire), [Python](https://www.pubnub.com/docs/sdks/python/api-reference/publish-and-subscribe.md#fire), [Ruby](https://www.pubnub.com/docs/sdks/ruby/api-reference/publish-and-subscribe.md#fire), [Swift](https://www.pubnub.com/docs/sdks/swift/api-reference/publish-and-subscribe.md#fire), and [Unity](https://www.pubnub.com/docs/sdks/unity/api-reference/publish-and-subscribe.md#fire) follow the same pattern using the SDK's `fire` method. Detailed initialization instructions are in the **Configuration** section of each SDK's documentation. #### JavaScript ```js try { const result = await pubnub.fire({ message: "Hello!", channel: "my_channel", sendByPost: false, // true to send via post meta: { cool: "meta", }, // fire extra meta with the request }); console.log("message published w/ timetoken", result.timetoken); } catch (status) { // handle error console.log(status); } ``` #### Swift ```swift pubnub.fire( channel: "my-channel", message: "Hello!" ) { result in switch result { case let .success(timetoken): print("Message Successfully Published at: \(timetoken)") case let .failure(error): print("Failed Response: \(error.localizedDescription)") } } ``` #### Kotlin ```kotlin val config = com.pubnub.api.v2.PNConfiguration.builder(UserId("myUserId"), "demo").apply { publishKey = "demo" } val channel = pubnub.channel("myChannel") channel.fire("Hello!").async { result -> result.onFailure { exception -> println("Error while publishing") exception.printStackTrace() }.onSuccess { value -> println("Message sent, timetoken: ${value.timetoken}") } } ``` #### Python ```python envelope = pubnub.fire() \ .channel('my_channel') \ .message('Hello!') \ .use_post(True) \ .sync() print('fire timetoken: %d' % envelope.result.timetoken) ``` #### C# ```csharp string message = "Hello!"; pubnub.Fire() .Message(message) .Channel(channel) .UsePOST(true) .Execute(new PNPublishResultExt( (result, status) => { if (status.Error) { // something bad happened. Console.WriteLine("error happened while publishing: " + pubnub.JsonPluggableLibrary.SerializeToJsonString(status)); } else { Console.WriteLine("publish worked! timetoken: " + result.Timetoken.ToString()); } } )); ``` #### Go ```go res, status, err := pn.Fire(). Channel("my-channel"). Message("Hello!"). Execute() ``` ### Using the REST API Send an HTTPS GET request to the [Fire API](https://www.pubnub.com/docs/sdks/rest-api/send-fire-request.md). Put the URL-encoded JSON message at the end of the path: ```bash curl 'https://ps.pndsn.com/publish/{pub_key}/{sub_key}/0/{channel}/0/%7B%22text%22%3A%22Hello!%22%7D?uuid={user_id}&auth={token}&norep=true&store=0' ``` | Parameter | Description | | --- | --- | | `pub_key` | Your publish key from the Admin Portal keyset configuration. | | `sub_key` | Your subscribe key from the Admin Portal keyset configuration. | | `channel` | The channel to fire the message to. | | `0` after the channel | The JSONP callback name. `0` means no callback. | | Last path segment | The JSON message payload, URL-encoded. | | `uuid` | The User ID of the sending system. | | `auth` | An Access Manager token your server granted with `write` on the channel. Required if Access Manager is enabled, unless the request is signed. | | `norep` | Set to `true` for Fire requests. A fired message isn't replicated across points of presence. | | `store` | Set to `0` so Message Persistence doesn't store the message. | A server that holds the secret key can sign the request with the `signature` and `timestamp` parameters instead of sending a token. See [Initialize a server SDK with a secret key](https://www.pubnub.com/docs/security/access-control/initialize-server-sdk.md). A successful request returns HTTP `200` with a JSON array. `1` and `"Sent"` mean PubNub accepted the message, and the last value is its timetoken: ```json [1, "Sent", "17901748369820336"] ``` If Access Manager rejects the request, it returns HTTP `403` and names the channel it refused: ```json {"error": true, "status": 403, "service": "Access Manager", "message": "Forbidden", "payload": {"channels": ["{channel}"]}} ``` Check that the token is valid, hasn't expired, and grants `write` on that channel. Last updated at: 2026-09-30T07:20:08.000Z