To create a Phantom via the PhantomBuster API, send a POST request to the /agents/save endpoint with the Phantom's script name (e.g. LinkedIn Search Export.js), the org set to "phantombuster", branch set to "master", and a display name. You can optionally include input arguments in JSON format. Test the request in the API reference first, then reuse it from your own tool.
Before you start
Before creating a Phantom via API, make sure:
-
Developer mode is enabled (optional, but useful to access additional API-related views in your Workspace) and you have a valid API key.
→ If you don't have one, see Create an API key. API keys can only be created by Workspace admins, if you don't see the Add API key button, check with your admin. - It’s also important to know which Phantom template to create.
→ This is done by copying the Phantom’s script name, which is always the Phantom name followed by .js- Get the exact Phantom name from the Phantom’s overview page in PhantomBuster (Solutions page → Learn more).
- The .js extension is required and must be included exactly as shown:
For example: LinkedIn Search Export.js
- Get the exact Phantom name from the Phantom’s overview page in PhantomBuster (Solutions page → Learn more).
How creating a Phantom via API works
Creating a Phantom via API means:
- Selecting an existing Phantom template.
- Creating a new Phantom instance in your Workspace.
- Optionally pre-filling its input at creation time.
This is done using the /agents/save endpoint.
The API reference is used to test and validate the creation request before reusing it from an external tool.
Create a Phantom from the API reference (testing)
Step 1: Open the create Phantom endpoint
- Open the PhantomBuster API reference.
-
In the left menu, go to:
PhantomBuster API v2 → Agents → POST /agents/save
→ This is the endpoint used to create or update a Phantom.
Step 2: Add your API key
- In the top-right corner, locate the Credentials section.
- In the Header, paste your API key into X-Phantombuster-Key.
Step 3: Fill in the required body parameters
In the Body params section, you must provide at least the following fields:
| Field | What to enter | What it’s used for |
|---|---|---|
| org | phantombuster (all lowercase) |
Indicates where the Phantom template is hosted. |
| script | The Phantom name, exactly as shown on the PhantomBuster Solutions page (the name is case-sensitive and must match exactly), with .js added at the end. For example: LinkedIn Post Likers Export.js LinkedIn Profile Scraper.js |
Tells PhantomBuster which Phantom to create. |
| branch | master (all lowercase) |
Ensures the Phantom is created using the default version. |
| name | A name for the new Phantom as it will appear in your PhantomBuster Workspace. For example: LinkedIn Post Likers Export - ICP Prospects |
Helps you identify the Phantom once it’s created in your PhantomBuster Dashboard. |
| argument (optional) | Input values in JSON format | Pre-fills the Phantom’s input at creation time. |
About input (arguments):
- Input is optional at creation time.
- If no argument is provided, the Phantom is created without input.
- In that case, input must be added manually in your PhantomBuster Workspace before launching.
Input formats depend on the Phantom and may include:
- A single URL.
- A Google Sheet or public CSV URL.
- A LinkedIn Leads list, if the Phantom is compatible with the LinkedIn Leads page.
→ To understand how arguments work and how to format them correctly, refer to How Phantom arguments work in the API.
Additional configuration fields (optional)
The /agents/save endpoint supports many additional fields beyond the required ones.
These map to settings that are available in most Phantom setups, such as:
- Execution limits
- Scheduling options
- Proxy settings
- Notifications
→ If you leave them empty, PhantomBuster will use the default settings for that Phantom.
This means:
- A Phantom can be safely created with only the key fields mentioned above.
- Advanced configuration can be:
- Added later from the dashboard, or
- Included directly in the API request for advanced use cases.
Step 4: Send the request
- Click Try it on the right-hand side of the API reference.
- If the request is successful, the response returns:
- A 200 status.
- An Agent ID for the newly created Phantom.
Step 5: Find your new Phantom in PhantomBuster
After the request:
- Go back to your PhantomBuster Dashboard.
- Locate the Phantom using the name provided in the request.
At this stage:
- The Phantom exists in the workspace.
- It behaves like a Phantom created from the Solutions page.
- It may still require input or settings if they weren’t provided in the API request.
- Once configured, it can be launched manually or via API.
Watch the video tutorial
This video shows how to create a Phantom via API using the /agents/save endpoint, then reproduce the same request in n8n to automate Phantom creation.
Frequently asked questions
What fields are required to create a Phantom via API?
You need org (set to "phantombuster"), script (the Phantom name with .js), branch (set to "master"), and name (the display name for your Workspace). Arguments are optional.
Can I configure the Phantom's input at creation time?
Yes. Pass the input values as JSON in the argument field. If you skip this, the Phantom is created without input and must be configured manually in your Workspace before launching.
Where do I find the correct script name?
Go to the Solutions page in PhantomBuster, click Learn more on the Phantom you want, and copy the exact name shown. Add .js at the end. The name is case-sensitive.
Can I create Workflows via API?
No. Only individual Phantoms can be created through the API. Workflows must be set up from the PhantomBuster Dashboard.