Campaign Management

Funding Instruments¶

GET accounts/:account_id/funding_instruments¶

Retrieve details for some or all funding instruments associated with the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/funding_instruments

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
funding_instrument_ids optional	Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `lygyi`
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: `created_at-asc`
with_deleted optional	Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	Include the `total_count` response attribute. Note: This parameter will be ignored if `cursor` is specified. Note: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false`

Example Request¶

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/funding_instruments

Example Response¶

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "2016-07-22T04:24:04Z",
      "description": "Visa ending in 0650",
      "credit_limit_local_micro": 200000000,
      "end_time": null,
      "id": "lygyi",
      "entity_status": "ACTIVE",
      "account_id": "18ce54d4x5t",
      "reasons_not_able_to_fund": [],
      "io_header": null,
      "currency": "USD",
      "funded_amount_local_micro": 645940000,
      "created_at": "2016-07-22T04:24:04Z",
      "type": "CREDIT_CARD",
      "able_to_fund": true,
      "updated_at": "2017-04-05T00:25:13Z",
      "credit_remaining_local_micro": null,
      "deleted": false
    }
  ]
}

GET accounts/:account_id/funding_instruments/:funding_instrument_id¶

Retrieve a specific funding instrument associated with the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/funding_instruments/:id

Parameters¶

Name Description

account_id

required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

funding_instrument_id

required

A reference to the funding instrument you are operating with in the request.

Type: string

Example: lygyi

with_deleted

optional

Include deleted results in your request.

Type: boolean

Default: false

Possible values: true, false

Example Request¶

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/funding_instruments/lygyi

Example Response¶

{
  "request": {
    "params": {
      "funding_instrument_id": "lygyi",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "start_time": "2016-07-22T04:24:04Z",
    "description": "Visa ending in 0650",
    "credit_limit_local_micro": 200000000,
    "end_time": null,
    "id": "lygyi",
    "entity_status": "ACTIVE",
    "account_id": "18ce54d4x5t",
    "reasons_not_able_to_fund": [],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": 645940000,
    "created_at": "2016-07-22T04:24:04Z",
    "type": "CREDIT_CARD",
    "able_to_fund": true,
    "updated_at": "2017-04-05T00:25:13Z",
    "credit_remaining_local_micro": null,
    "deleted": false
  }
}

POST accounts/:account_id/funding_instruments¶

SANDBOX ONLY

Create a funding instrument in the sandbox environment.

There is no risk of incurring costs while using a sandbox funding instrument.

Resource URL¶

https://ads-api-sandbox.twitter.com/3/accounts/:account_id/funding_instruments

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `gq1844`
currency required	The currency, expressed in ISO-4217. Type: string Example: `USD`
start_time required	The date for the funding instrument to become active and usable, expressed in ISO 8601. Type: string Example: `2017-05-19T07:00:00Z`
type required	The type of funding instrument to create. Type: enum Possible values: `AGENCY_CREDIT_LINE`, `CREDIT_CARD`, `CREDIT_LINE`, `INSERTION_ORDER`, `PARTNER_MANAGED`
end_time sometimes required	The date for the funding instrument to become inactive, expressed in ISO 8601. Type: string Example: `2017-05-26T07:00:00Z`
credit_limit_local_micro optional	The total credit available against this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: `37500000`
funded_amount_local_micro optional	The total budget amount allocated to this funding instrument. Note: Only applicable to some funding instrument types. Type: long Example: `37500000`

Example Request¶

POST https://ads-api-sandbox.twitter.com/3/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000

Example Response¶

{
  "data": {
    "start_time": "2017-07-10T00:00:00Z",
    "description": "(no payment method has been set up yet)",
    "credit_limit_local_micro": null,
    "end_time": "2018-01-10T00:00:00Z",
    "id": "hxtet",
    "entity_status": "ACTIVE",
    "account_id": "gq1844",
    "reasons_not_able_to_fund": [],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": 140000000000,
    "created_at": "2017-09-09T05:23:28Z",
    "type": "INSERTION_ORDER",
    "able_to_fund": true,
    "updated_at": "2017-09-09T05:23:28Z",
    "credit_remaining_local_micro": null,
    "deleted": false
  },
  "request": {
    "params": {
      "start_time": "2017-07-10T00:00:00Z",
      "end_time": "2018-01-10T00:00:00Z",
      "account_id": "gq1844",
      "currency": "USD",
      "funded_amount_local_micro": 140000000000,
      "type": "INSERTION_ORDER"
    }
  }
}

PUT accounts/:account_id/funding_instruments/:funding_instrument_id¶

Update the specified partner managed funding instrument, belonging to the current account and current partner application ID. See Partner Managed Funding Instruments for more details on these types of funding instruments.

PMFI specific error codes:

FUNDING_INSTRUMENT_EXCEEDS_AVAILABLE_CREDIT_LIMIT
FUNDING_INSTRUMENT_ACCESS_NOT_ALLOWED
FUNDING_INSTRUMENT_NOT_FOUND
FUNDING_INSTRUMENT_SPEND_EXCEED_FUNDED_AMOUNT

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters¶

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: `hkk5`
funding_instrument_id required	A reference to the funding instrument you are operating with in the request. Type: string Exampple: `hw6ie`
funded_amount_local_micro optional	The total budget amount allocated to this funding instrument. Type: long Example: `37500000`
paused optional	Whether this funding instrument should be paused. Type: boolean Possible values: `false`, `true`

Example Request¶

PUT https://ads-api.twitter.com/3/accounts/hkk5/funding_instruments/hw6ie?funded_amount_local_micro=1000000000

Example Response¶

{
  "data": {
    "end_time": null,
    "created_at": "2012-11-08T02:31:46Z",
    "updated_at": "2012-11-20T23:20:35Z",
    "account_id": "hkk5",
    "id": "hw6ie",
    "entity_status": "ACTIVE",
    "deleted": false
    "type": "RESELLER",
    "credit_limit_local_micro": null,
    "funded_amount_local_micro": 1000000000,
    "currency": "USD",
    "description": "CustomerName funding instrument",
    "start_time": "2012-11-08T02:31:46",
    "serving_status": "ACTIVE"

  },
  "request": {
    "params": {
      "account_id": "hkk5",
      "funding_instrument_id": "hw6ie",
      "funded_amount_local_micro": 1000000000
    }
  }
}

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id¶

SANDBOX ONLY

Delete a funding instrument in the sandbox environment.

Resource URL¶

https://ads-api-sandbox.twitter.com/3/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters¶

Name Description

account_id

required

Type: string

Example: gq1844

funding_instrument_id

required

A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: hxt82

Example Request¶

DELETE https://ads-api-sandbox.twitter.com/3/accounts/gq1844/funding_instruments/hxt82

Example Response¶

{
  "data": {
    "start_time": "2017-08-30T19:23:47Z",
    "description": "(no payment method has been set up yet)",
    "credit_limit_local_micro": 500000000,
    "end_time": null,
    "id": "hxt82",
    "entity_status": "ACTIVE",
    "account_id": "gq1844",
    "reasons_not_able_to_fund": [
      "DELETED"
    ],
    "io_header": null,
    "currency": "USD",
    "funded_amount_local_micro": null,
    "created_at": "2017-08-30T19:23:47Z",
    "type": "CREDIT_CARD",
    "able_to_fund": false,
    "updated_at": "2017-09-09T02:08:30Z",
    "credit_remaining_local_micro": null,
    "deleted": true
  },
  "request": {
    "params": {
      "funding_instrument_id": "hxt82",
      "account_id": "gq1844"
    }
  }
}