2 Using the Account Manager Web Service

The following chapter describes the Account Manager Web service. The Account Manager Web service configures organizations and users for the application GUI.

Authorized Users

Only users who belong to the system owner organization can create all organizations and users. Users who belong to an ad service provider organization can create their own ad space owner organizations and users and their own advertiser organizations and users.

Errors

Errors are returned in a SOAP Message that includes a human readable faultstring element that describes the error.

Return Data Structures

The following data structures are returned in the Account Manager web service.

User

Table 2-1 describes the User data structure.

Table 2-1 The User Data Structure

Element Name	Type	Description
role	tns:userRoleEnum	Describes the type of user. One of the following: ServiceOwnerUser NetworkProviderUser AdServiceProviderUser AdSpaceOwnerUser AdvertiserUser
name	xs:string	Username assigned to this user.
id	xs:long	User ID assigned to this user in the system.
managedOrganizationId	xs:long	System generated organization ID for the organization associated with this user.
email	xs:string	Email address of the user, given when the user was created.

Organization

Table 2-2 describes the Organization data structure.

Table 2-2 The Organization Data Structure

Element Name	Type	Description
id	xs:long	Organization ID assigned to this organization in the system.
name	xs:string	Organization name assigned at creation.
autoApproved	xs:boolean	Allow automatic approval of campaign spaces (significant only in the case of Ad Space Owners).
description	xs:string	Description given when the organization was created.
extID	xs:string	An external identifier for correlation outside of the system.
type	tns:orgTypeEnum	The type of the organization. One of the following: NetworkProvider AdServiceProvider AdSpaceOwner Advertiser

Operations

The following describes the operations available in the Account Manager web service.

Operation: createOrganization

Creates a new organization

Table 2-3 Input Message Parameter: complexType - createOrganization

Element	Type	Description
OrganizationType	tns:orgTypeEnum	One of the following: NetworkProvider AdServiceProvider AdSpaceOwner Advertiser
Name	xs:sting	Name for the organization in the system.
Description	xs:string	Optional. Descriptive string for the organization.
ExternalID	xs:string	An external identifier for correlation outside of the system.
ParentId	xs:long	Optional. The system ID for the parent organization. Default value is managedOrganizationId. See Table 2-1.
AutoApproved	xs:boolean	Allow automatic approval of campaign spaces (significant only in the case of Ad Space Owners).]

createOrganizationResponse:

Table 2-4 Output Message Parameter: complexType: createOrganizationResponse

Element	Type	Description
Organization	tns:organization	See Table 2-2.

Operation:createUser

Creates a new user account for the Organization with a given orgId

Table 2-5 Input Message Parameter: complexType - createUser

Element	Type	Description
OrganizationId	xs:long	Optional. The system ID returned upon organization creation.] Default value is managedOrganizationId. See Table 2-1.
UserName	xs:sting	Name for this user.
Password	xs:string	Password for this user.
Email	xs:string	Email address to notify this user.

createUserResponse:

Table 2-6 Output Message Parameter: complexType - createUserResponse

Element	Type	Description
User	tns:user	See Table 2-1.

Operation: deleteOrganization

Deletes an organization

Table 2-7 Input Message Parameter: complexType - deleteOrganization

Element	Type	Description
OrganizationId	xs:long	ID assigned to this organization in the system.

Operation: deleteUser

Deletes a user from an organization

Table 2-8 Input Message Parameter: complexType - deleteUser

Element	Type	Description
Id	xs:long	User ID assigned to this organization in the system.

Operation:getOrganizationByExternalId

Retrieves an organization by the external ID associated with it when it was created

Table 2-9 Input Message Parameter: complexType - getOrganizationByExternalId

Element	Type	Description
ExternalId	xs:string	An external identifier for correlation outside of the system, assigned at creation.

getOrganizationByExternalIdResponse

Table 2-10 Output Message Parameter: complexType - getOrganizatinByExternalIdResponse

Element	Type	Description
Organization	tns:organization	See Table 2-2.

Operation:getOrganizationById

Retrieves an organization by the id assigned to it by the system when it was created

Table 2-11 Input Message Parameter: complextType - getOrganizationByID

Element	Type	Description
OrganizationId	xs:long	ID assigned to the organization by the system.

getOrganizationByIdResponse:

Table 2-12 Output Message Parameter: complexType - getOrganizationByIdResponse

Element	Type	Description
Organization	tns:organization	See Table 2-2.

Operation: getOrganizationByName

Retrieves an organization by the name assigned to it when it was created

Table 2-13 Input Message Parameter: complexType - getOrganizationByName

Element

Type

Description

OrganizationType

tns:orgTypeEnum

One of the following:

NetworkProvider
AdServiceProvider
AdSpaceOwner
Advertiser

Name

xs:string

Name for the organization in the system

ParentId

xs:long

Optional.

The system ID for the parent organization.

Default value is managedOrganizationId. See Table 2-1.

getOrganizationByNameResponse:

Table 2-14 Output Message Parameter: complexType - getOrganizationByNameResponse

Element	Type	Description
Organization	tns:organization	See Table 2-2.

Operation: listOrganizations

Gets a list of organizations

Table 2-15 Input Message Parameter: complexType - listOrganizations

Element	Type	Description
OrganizationType	tns:orgTypeEnum	One of the following: NetworkProvider AdServiceProvider AdSpaceOwner Advertiser
FirstResult	xs:int	The index position of the first result.
MaxResults	xs:int	The maximum number of results to return. Note: Do not use zero.
ParentId	xs:long	Optional. The system ID for the parent organization. Default value is managedOrganizationId. See Table 2-1.

listOrganizationResponse

Table 2-16 Output Message Parameter: complexType - listOrganizationsResponse

Element	Type	Description
OrganizationList	tns:organization	List of data structures described in Table 2-2.

Operation: listUsers

Returns a list of users for an Organization

Table 2-17 Input Message Parameter: complexType - listUsers

Element	Type	Description
OrganizationId	xs:long	Optional. ID assigned to the organization by the system. Default value is managedOrganizationId. See Table 2-1.
FirstResult	xs:int	Optional. Index position of the first result. Default value is 0.
MaxResults	xs:int	Optional. Maximum number of results to return. Default value is 0.

Element

Type

Description

OrganizationId

xs:long

Optional.

ID assigned to the organization by the system.

Default value is managedOrganizationId. See Table 2-1.

FirstResult

xs:int

Optional.

Index position of the first result.

Default value is 0.

MaxResults

xs:int

Optional.

Maximum number of results to return.

Default value is 0.

listUsersResponse

Table 2-18 Output Message Parameter: complexType - listUsersResponse

Element	Type	Description
UserList	tns:user	List of data structures described in Table 2-1.