Customer API of your panel

The basics

The API has one address on your own domain, and your customers see it, together with a ready-made description, on the API page of their account. For a panel on example.com it is https://example.com/api/v2. For the background, see the SMM panel API explained.

• Send a POST request.
• Send the fields as form fields (application/x-www-form-urlencoded).
• Every request needs key (the customer's API key) and action (what to do), plus the fields of that action.
• Every answer is JSON.
• The API follows the common format, so most panels and tools that support it can connect with only the address and the key. Subscription orders differ in a few details, listed below.

A sample request that places an order: curl -X POST https://example.com/api/v2 -d key=YOUR_API_KEY -d action=add -d service=1 -d link=https://example.com/profile -d quantity=1000.

The prices, balance and amounts are in the currency of your panel. Provider service numbers and provider order numbers are never part of an answer: customers only see your own numbers.

The API key

• Each customer has one key. It is the only thing that identifies them in the key parameter.
• On the API page of their account, a customer can choose Generate new key. This needs their current password.
• The key is shown once, right after it is generated. A customer who lost the key generates a new one.
• A new key makes the old key invalid at once. Every tool that used the old key stops working until it gets the new one.
• A key is refused if it is missing, wrong or longer than 191 characters, or if the account is closed.

Tell your customers to keep the key private: anyone who has it can place orders with their balance.

Answers and errors

A mistake in the request is not an HTTP error. The answer has the status HTTP 200 and the body has one field: {"error":"Incorrect service ID"}. A client must look for the error field in every answer.

• Invalid API key: the key is missing, wrong, or the account is closed.
• Incorrect request: action is missing or unknown, a required parameter is missing, the quantity is not a whole number, runs or interval was sent on its own, or more than 100 numbers were sent in one request.
• Incorrect service ID: the service does not exist or is not for sale.
• Incorrect link: the link is longer than 191 characters.
• Quantity less than minimal N and Quantity more than maximal N: the quantity is outside the limits of the service (N is the limit).
• Not enough funds on balance: the balance cannot pay the order.
• Drip-feed is not available for this service: runs or interval was sent to a service that does not support drip-feed.
• Runs less than minimal 2, Runs more than maximal 1000, Interval less than minimal 1, Interval more than maximal 10080: drip-feed values outside the limits.
• Incorrect order ID: the order does not exist or does not belong to the key.
• Refill is not available for this order, Refill not found and Cancel is not available for this order: see the refill and cancel actions below.
• Incorrect followed by a field name, for example Incorrect comments: a field of a service type with extra order fields has the wrong format.
• Internal server error: a fault on the server, sent with HTTP 500. The result of the request is unclear, so the customer should check the balance and the orders before sending the same order again.
• Too many requests: sent with HTTP 429 and a Retry-After header when the key sends requests too fast. Wait for the number of seconds in the header.

If you set a service to refuse a second open order with the same link, the add answer can also be {"error":"You have an active order with this link. Please wait until order being completed."}.

services: the list of services

Parameters: key, action=services.

The answer is a list with one entry for every service that is for sale. Each entry has:

• service: the service number you use in add.
• name and category: the service name and its category.
• type: Default for a standard service, Subscriptions for a subscription, or the name of a service type that takes extra order fields.
• rate: the price per 1000 for the key owner, in your panel currency. This is the price of the account, so two customers can see different rates.
• min and max: the smallest and the largest quantity of one order.
• refill and cancel: true when the service accepts that request through the API.
• dripfeed: true when drip-feed orders (runs and interval) are possible.

Sample answer, shortened to one entry: [{"service":1,"name":"Instagram Followers","type":"Default","category":"Instagram","rate":"0.90","min":"50","max":"10000","refill":true,"cancel":true,"dripfeed":true}].

add: place an order

Parameters for a standard service:

• key and action=add: required.
• service: required, the number from the service list.
• link: required, the page or the username to work on, up to 191 characters.
• quantity: required, a whole number between min and max of the service.
• runs and interval: optional, for a drip-feed order, and sent together. runs is the number of runs (2 to 1000). interval is the minutes between two runs (1 to 10080).

The answer is the order number: {"order":23501}. The price is taken from the balance at once. For a drip-feed order the number is the number of the first run, the whole price is taken at once, and the later runs are placed interval minutes apart.

Services of type Subscriptions use other parameters instead of link and quantity:

• username: required, the account to follow.
• min and max: the smallest and the largest quantity per post, within the limits of the service.
• posts: the number of new posts to process. It is required, because unlimited subscriptions are not available.
• old_posts: optional, the number of existing posts to process.
• delay: minutes of delay, one of 0, 5, 10, 15, 20, 30, 40, 50, 60, 90, 120, 150, 180, 210, 240, 270, 300, 360, 420, 480, 540 or 600.
• expiry: optional end date as dd/mm/yyyy, after today.

The answer has the same shape, {"order":1000000001}, but this number is a subscription number, not an order number. Subscription numbers start from 1000000001. The fee is (posts + old_posts) times max times the price, divided by 1000, and it is taken when the subscription opens. The part for posts that were not processed is returned when the subscription completes, expires or is canceled.

Services with extra order fields (service types) take their own fields in place of or next to link and quantity. Drip-feed is not available for them. The answer is the same as for a standard order. A missing field gives Incorrect request, and a field in the wrong format gives Incorrect and the field name.

• Package: link. The price is the listed rate, once; quantity is ignored.
• SEO: link, quantity and keywords.
• Custom Comments: link and comments, one comment per line. quantity is ignored; it is the number of comments.
• Mentions: link, quantity and usernames, separated by commas or line breaks.
• Mentions with Hashtags: link, quantity, usernames and hashtags.
• Mentions Custom List: usernames, one per line. link and quantity are ignored.
• Mentions Hashtag: link, quantity and hashtag.
• Mentions User Followers: link, quantity and username.
• Mentions Media Likers: link, quantity and media.
• Poll: link, quantity and answer_number, a whole number from 1.
• Comment Replies: username and comments, one reply per line. link and quantity are ignored.
• Web Traffic: link, quantity, country, device and type_of_traffic; google_keyword and referring_url are optional.

The type value in the service list tells which of these a service uses. The API page of the customer account always shows the exact list of fields of your panel.

status: follow orders

One order: key, action=status and order. The answer has charge, start_count, status, remains and currency. For example {"charge":"0.27819","start_count":"3572","status":"Partial","remains":"157","currency":"USD"}.

• charge is the net amount: the price of the order minus anything that was refunded.
• start_count is the count when the work started, and remains is the quantity left.
• status is one of Pending, Processing, In progress, Completed, Partial, Canceled or Refunded.
• Incorrect order ID is returned for an order that does not exist or belongs to someone else.

Several orders: send orders as numbers separated by commas, up to 100, instead of order. The answer is an object whose keys are the numbers you sent. A number that is not found gets an error instead: {"1":{"charge":"0.27819","start_count":"3572","status":"Partial","remains":"157","currency":"USD"},"10":{"error":"Incorrect order ID"}}. More than 100 numbers give Incorrect request for the whole request.

A subscription number gives another answer, with status (Active, Paused, Completed, Expired or Canceled), expiry (dd/mm/yyyy or empty), posts (the number of posts processed) and orders (the numbers of its post orders).

balance, refill, refill_status and cancel

balance: key and action=balance. The answer is {"balance":"100.84292","currency":"USD"}.

refill: key, action=refill and order, or orders with up to 100 numbers separated by commas. It opens a refill request for a Completed or Partial order whose service has refill set to true. The answer is the refill number, {"refill":1}. With orders the answer is a list, one entry for each order: [{"order":1,"refill":1},{"order":2,"refill":{"error":"Refill is not available for this order"}}].

• A refill is refused when the service does not allow refill, when the order belongs to a subscription or a drip-feed order, when the order is not Completed or Partial, when a refill for the order is already open, when the last refill of the order was completed less than 24 hours ago, when the key already has 50 open refill and cancel requests, or when refill requests through the API are turned off for the account.

refill_status: key, action=refill_status and refill, or refills with up to 100 numbers. The answer is {"status":"Completed"}, or a list such as [{"refill":1,"status":"Completed"},{"refill":2,"status":{"error":"Refill not found"}}]. The status is Pending, In progress, Completed, Rejected or Error. A customer can only see their own refills.

cancel: key, action=cancel and orders with up to 100 numbers. It opens a cancel request for each order whose service has cancel set to true and whose status is Pending, In progress or Processing. The answer is a list: [{"order":2,"cancel":1},{"order":9,"cancel":{"error":"Incorrect order ID"}}].

• "cancel":1 means the request was opened. It is not an instant cancellation and nothing is refunded yet.
• When the provider cancels the order, its status becomes Canceled, or Partial if part was already delivered, and the undelivered part goes back to the customer's balance. The customer follows the result with status.
• A cancel request is refused with Cancel is not available for this order when the service does not allow cancel, when the order belongs to a subscription or a drip-feed order, when it has another status, when a cancel request is already open, or when the key already has 50 open requests.

Actions between Arty panels

The actions add_status, add_batch, batch_status, panel_info, push_register and push_unregister are for one Arty panel talking to another. They let a panel that uses yours as its provider send orders in packets, follow them without sending an order twice, and receive status changes within about 30 seconds. They are used automatically when your customer is an Arty panel. Normal customers and tools never need them.

Sending order packets needs a connection that Arty has verified, and it is refused with HTTP 403 otherwise. Reading the result of a packet that was already sent is still possible.

For the other side of the connection, where your panel is the customer of a provider, read Providers.