defaultheader

GET campaign {#get}

Get data of one campaign object.

Parameters

Parameters | Detail ----------------------- | ------------- with
optional |Returns sub-object or count of sub-objects relating to the campaign. If sub-object is requested, response will return the first 20 records
Accepted value: "ideacount", "commentcount", "votecount", "membercount" format
optional|Specifies returned data format
Accepted value: "json", "xml"

Resource Information

Authentication: See Access Permission for GET campaign

HTTP Methods: GET

Request URL Format: https://{api_domain}/api3/campaign

Access Permission {#GetPermission}

Access to data varies base on system settings and requester roles. See Oauth 2.0 for details on authentication.

Private WebStorms: Requester must authenticate to get data.

Public WebStorms: No authentication required to get data.

Requster Role: Some response attributes are accessible base on the requester's role.

campaign_options: Specify the campaign options enabled in the webstorm

"Public Site": The campaign is public

"Disable Vote": Voting is disabled for the campaign

"Idea Tags": Idea Tags are enabled for the campaign

"Disable Comment": Comment is disabled for the campaign

"Disable Demote": Demote is disabled for the idea

Errors

  • Invalid object ID or you don't have access to this object

Example Request

  • Method: GET
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c

  • URL: https://example.brightidea.com/api3/campaign/E62DB922-55EE-419D-9CB9-4C4DD8243ADA?with=idea_count

    ~~~ { "campaign": { "id": "F27B8A3F-C38B-460E-8F73-AA092A39FA2E", "name": "Great Campaign", "description": "Great Campaign Description", "datecreated": "2013-05-16 12:45:24.380", "status": "Active", "campaignoptions": [ { "optionid": "316", "optionenabled": false, "description": "Public Site" }, { "optionid": "331", "optionenabled": false, "description": "Disable Vote" }, { "optionid": "337", "optionenabled": true, "description": "Idea Tags" }, { "optionid": "344", "optionenabled": false, "description": "Disable Comment" }, { "optionid": "360", "optionenabled": false, "description": "Disable Demote" } ], "idea_count": 6 } } ~~~




LIST campaign {#list}

Get data on a list of campaign objects. Objects are order by created date descending by default.

On retrieving large set of data, requester should use pagination parameters such as page and page_size to manage multiple requests.

Parameters

Parameters | Detail ----------------------------------- | ----------------------------------- id
optional |Filter return by campaign ID
Sample value: "11111111-1111-1111-1111-111111111111" name
optional |Filter return by campaign title
Sample value: "Great Campaign Title" date_created
optional |Filter return by campaign created date. Response contains all campaigns created within the 24 hours of the specified date
Sample value: "12/06/2009" status
optional |Filter return by campaign state. Parameter is for Admin only
Accepted Value: 1: For active, 2: For closed, 3: For archived start_date
optional |Filter return by campaign start date.
Sample value: "12/06/2009" end_date
optional |Filter return by campaign end date.
Sample value: "12/06/2009" status
optional |Filter return by campaign state. Parameter is for Admin only
Accepted Value: "active", "closed", "archived" page_size
optional |Specifies number of records returns per page. Default: 20. Minimum: 1. Maximum: 100
Sample value: 50 page
optional |Specifies which page of records to return. Default: 1. Minimum: 1. Maximum: {pagecount}
Sample value: 5 order
optional |A SQL style string that specifies the order the records should return in.
Sample value: "datecreated ASC, screenname DESC".
Accepted attributes: "id", "name", "datecreated", "status", "random" with
optional |Returns sub-object or count of sub-objects relating to the campaign. If sub-object is requested, response will return the first 20 records
Accepted value: "idea_count", "image" format
optional |Specifies returned data format
Accepted value: "json", "xml"

Resource Information

Authentication: See Access Permission

HTTP Methods: GET

Request URL Format: https://{api_domain}/api3/campaign

Access Permission {#listPermission}

Access to data varies base on system settings and requester roles. See Oauth 2.0 for details on authentication.

Private WebStorms: Requester must authenticate to get data.

Public WebStorms: No authentication required to get data.

Requster Role: Some response attributes are accessible base on the requester's role.

Errors

  • Invalid object ID or you don't have access to this object

Example Request

  • Method: GET
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c

  • URL: https://example.brightidea.com/api3/campaign?page=2&page_size=5

    ~~~ { "campaign_list": [

            {
            "id": "1FCEB03C-A11B-49B7-BE2C-F7C576920782",
            "name": "Sample Campaign",
            "description": "Sample Campaign Description",
            "date_created": "2012-09-14 17:04:57.383",
            "status": "Active",
             "start_date": "2012-03-21 20:07:57.627",
             "end_date": "2013-03-21 20:07:57.627"
        },
        {
            "id": "0642E3ED-AAC3-47B6-9E0B-902B6596AC53",
            "name": "Chips Voting Campaign",
            "description": "Chips Voting Campaign Description",
            "date_created": "2012-02-07 17:51:50.600",
            "status": "Archived",
            "start_date": "2011-05-18 23:15:46.567",
            "end_date": "2012-05-17 23:15:46.567"
        },
        {
            "id": "F27B8A3F-C38B-460E-8F73-AA092A39FA2E",
            "name": "Great Campaign",
            "description": "Great Campaign Description",
            "date_created": "2013-05-16 12:45:24.380",
            "status": "Closed",
            "start_date": "2012-02-23 17:07:50.473",
            "end_date": "2013-02-22 17:07:50.473",
             "start_date": "2011-08-01 16:28:53.687",
            "end_date": "2012-07-31 16:28:53.687"
        },
        {
            "id": "1F93FD4F-F06D-456A-AFE9-825CE9B591F2",
            "name": "Private Campaign ",
            "description": "This is a Private Campaign ",
            "date_created": "2012-04-25 10:26:03.557",
            "status": "Active",
            "start_date": "2011-05-05 16:09:54.997",
            "end_date": "2012-05-04 16:09:54.997"
        },
        {
            "id": "0E3C90CC-2261-4F12-A7EF-EF32939842F6",
            "name": "Public Campaign ",
            "description": "This is a Public Campaign ",
            "date_created": "2011-05-03 13:40:49.843",
            "status": "Active",
            "start_date": "2011-09-09 12:07:18.843",
            "end_date": "2012-09-08 12:07:18.843"
        },

    ],
    "stats": {
        "total": 12,
        "page_count": 3,
        "current_page": 2
    }
}

    ~~~




CREATE campaign {#create}

Create a campaign object.

Requester must be Admin of the Affiliate to create campaign.

Parameters

Parameters | Detail ----------------------------------- | ----------------------------------- name
required |This is the name of the campaign.
Sample value: "Great Campaign Title" description
optional |This is the description of the campaign. It's a long text field. Minimum 1 character.
Sample value: "Great Campaign Description" template_campaign
optional |This is the ID of the template campaign.
Sample value: "11111111-1111-1111-1111-111111111111" domain
optional |This is the domain of the campaign.
Sample value: "domain.company.com" alias
optional |This is the campaign name alias.
Sample value: "democampaign"

Resource Information

Authentication: Required. See Oauth 2.0 for details on authentication.

HTTP Methods: POST

Request URL Format: https://{api_domain}/api3/campaign

Access Permission

Requester must be an Affiliate Admin to create campaign. See Oauth 2.0 for details on authentication.

Errors

  • A campaign with this name already exists
  • {parameter} must be more than {minimum_length} characters
  • {parameter} must be less than {maximum_length} characters
  • Invalid {parameter} received

Example Request

  • Method: POST
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c
  • URL: https://example.brightidea.com/api3/campaign

  • Form data:

    • name=Great Campaign
    • description=Great Campaign Description

    ~~~ {

    campaign:{ id: "F27B8A3F-C38B-460E-8F73-AA092A39FA2E" name: "Great Campaign" description: "Great Campaign Description" date_created: "2013-05-16 12:45:24.380" } } ~~~




UPDATE campaign {#update}

Update a campaign object.

Function updates only value of parameters passed through request. To empty out an attribute, pass parameter with blank value.

Parameters

Parameters | Detail ----------------------------------- | ----------------------------------- name
optional |This is the name of the campaign.
Sample value: "Great Campaign Title" description
optional |This is the description of the campaign. It's a long text field. Minimum 1 character.
Sample value: "Great Campaign Description"

Resource Information

Authentication: Required. See Oauth 2.0 for details on authentication.

HTTP Methods: PUT

Request URL Format: https://{api_domain}/api3/campaign/{id}

Access Permission

Authentication is required for UPDATE campaign request. See Oauth 2.0 for details on authentication.

Affiliate Admin can make update for all campaigns.

Errors

  • {parameter} must be more than {minimum_length} characters
  • {parameter} must be less than {maximum_length} characters
  • Invalid {parameter} received
  • campaign doesn't exist
  • Password doesn't satisfy requirement
  • Failed to update campaign

Example Request

  • Method: PUT
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c
  • URL: https://example.brightidea.com/api3/campaign/AF7C07AC-0D23-4673-918C-2AD13B7747D5

  • Form data:

    • name=Great Campaign
    • description=Great Campaign Description

    ~~~ { campaign: { id: "4E4D9246-E3BD-4C99-9CD9-233A1B766E07" name: "Great Campaign" description: "Great Campaign Description" date_created: "2013-04-25 15:44:44.687" } } ~~~




DELETE campaign {#delete}

Delete a campaign object. Requester must be an Admin.

Parameters

Parameters | Detail ----------------------------------------| ----------------------------------- format
optional |Specifies returned data format
Accepted value: "json", "xml"

Resource Information

  • Authentication: Required
  • HTTP Methods: DELETE
  • Request URL Format: https://{api_domain}/api3/campaign/{id}

Access Permission

Requester must be an Admin.

Errors

  • Invalid GUID received

Example Request

  • Method: DELETE
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c

  • URL: https://example.brightidea.com/api3/campaign/8B3E8DFF-83B3-403D-BB69-28223F418676

    ~~~ { "message": "success", "code": 200 } ~~~




FAQ {#faq}

Question: LIST campaign only return 100 objects maximum per request. How do I retrieve more results.

Answer: LIST campaign response is automatically paginated. If you got 100 idea objects in the initial request, pass "page_size=100&page=2" to get the next 100. page_count is returned with every LIST request so your application can figure out when it hits the last page.