Rapattoni Developer Resources

Authentication

Magic API access is secured via OAuth2; a transaction with our identity server is required to obtain the necessary bearer token. Currently only the Client Credential grant type is supported.
For Client Credential Grant access, the following parameters must be passed in the body of a POST transaction:

  • grant_type: Client Credential access will always use the client_credentials grant type.
  • client_id: An id provided by the Association staff.
  • client_secret: A value provided by the Association staff, associated with the client_id.
  • scope: Provided by the Association staff. This must match a scope that the API recognizes and that is approved for usage by your credentials. It is part of what defines what you can access in the API.

The body of the request should look similar to the following example:

  • grant_type=client_credentials&client_id=ClientID&scope=Scope&client_secret=Secret

You will also need to include the header:Content-Type: application/x-www-form-urlencoded

If the transaction is successful, then the response body will be a JSON object containing the access token, the token expiration date, and the token type. The token type will always be “bearer”, and the time till the token expires is set by the association, on a client by client basis, based upon their rules and regulations.


API Transactions

All transactions must include the Authorization header with the value being the client’s current bearer token obtained from the transaction with our identity server.

Here is an example of the how the Authorization header with the bearer token should appear in the HTTP request. Please note that the actual token hash will be substantially longer:

  • Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiI

Depending on your setup you may need to preemptively URL encode your query. The following is an example of the URL with an encoded query segment:

  • https://api.rapmagic.com/cust/odata/Members?%24select=MemberKeyNumeric%2CMemberFirstName%2CMemberLastName%2CMemberNationalAssociationId%2COfficeName

The Magic API utilizes standard OData URIs and commands (ODatav4).

Responses, unless otherwise specified, will be in the JSON format.

The Service Document is available via a get request against the root URL (https://api.rapmagic.com/cust/odata). By default, this will return in the XML format but can be requested in JSON by passing “application/json” in the Accept header. This document is a standard OData resource listing all top-level entity sets exposed by the service.( ODatav4 10.1)

The Metadata Document is available via a get request against the root URL with “/$metadata” appended (i.e. https://api.rapmagic.com/cust/odata/$metadata). This resource describes the API’s data model; including data types, relationships between entity sets, and available fields (ODatav4 11.1.2). This resource is only available in the XML format.

Entity Set Queries: All Entity Set queries use the default OData format; the root URL is appended with “/EntitySet” (i.e. to query the Offices Entity Set: https://api.rapmagic.com/cust/odata/Offices)
When Querying against Entity Sets, the Magic API Supports most OData 4 query options, functions and operators. The below list are those query options and some of their associated supported functions and operators. Please see the OData 4 specification for further information in regards to these:

  • $expand: allows for the inclusion of entities related to the base entity set queried. The relationships between entity sets can be found in the metadata document. Multiple entities can be included with comma delimiting. If the relationship is further than 1 degree of separation than the full path to the targeted entity must be included. (ODatav4 11.2.4.2)
    Examples:
    • Members?$expand=MemberDesignations: this will return Member records and their related MemberDesignations entries. The Metadata will show Members and MemberDesignations are via MemberKeyNumeric.
    • Members?$expand=MemberDesignations($expand=Designations): this will return Member records, their related MemberDesignations entries and the related information to describe the Designations. The Members set links to MemberDesignations via MemberKeyNumeric and the MemberDesignations set links to Designations on the MemberDesignation key.
  • $select: specify fields to be returned, if not included all fields will be returned. For selecting fields from expanded entity set relationships, the select is included with the expanded item. (ODatav4 11.2.4.2)
    Examples:
    • Members?$select=MemberKeyNumeric,MemberFirstName
    • Members?$expand=MemberDesignations($select=MemberDesignation)&$select=MemberKeyNumeric,MemberFirstName
  • $top: specify the number of entities to return (ODatav4 11.2.5.3)
    • Members?$top=10
  • $skip: skip over the first n entities prior to returning data (ODatav4 11.2.5.4)
    Example:
    • Members?$skip=10
  • $orderby: order the results by a specific field’s value; use asc or desc to specify ascending or descending. To order by multiple criteria use comma delimiting(ODatav4 11.2.5.2)
    Examples:
    • Members?$orderby=MemberFirstName asc
    • Members?$orderby=MemberFirstName asc, OfficeName desc
  • $count: $count=true specifies that the total count of entities matching the request must be returned along with the results (ODatav4 11.2.5.5)
    Example:
    • Members?$count=true
  • $filter: restrict the returned entities to only those matching the filter criteria (ODatav4 11.2.5.1)
    • Operators
      • eq: Equal
      • ne: Not equal
      • gt: Greater than
      • ge: Greater than or equal
      • lt: Less than
      • le: Less than or equal
      • and: Logical and
      • or: Logical or
      • not: Logical negation, used in conjunction with other functions and operators to create a negative comparison.
      • add: add to modify a numeric field and utilize the result for comparisons.
      • sub: subtract to modify a numeric field and utilize the result for comparisons.
      • mul: multiply to modify a numeric field and utilize the result for comparisons.
      • div: divide to modify a numeric field and utilize the result for comparisons.
      • (): Functions and operators can be nested using parentheses for precedence.
    • Functions
      • contains: string contains, syntax is: contains(FieldName,’string’)
      • endswith: string ends with, syntax is: endswith(FieldName,’string’)
      • startswith: string starts with, syntax is: startswith(FieldName,’string’)
      • substring: string contains, syntax is: substring(FieldName,1) eq 'string'
      • tolower: string to lower casing
      • toupper: string to upper casing
      • trim: trim all leading and trailing white spaces from a string
      • concat: append one string value to another
      • day: return the day component from a DateTimeOffset or Date
      • hour: return the hour component from a DateTimeOffset
      • minute: return the minute component from a DateTimeOffset
      • second: return the second component from a DateTimeOffset
      • month: return the month component from a DateTimeOffset or Date
      • year: return the year component from a DateTimeOffset or Date
    • Complex Filter Example:
      • Offices?$filter=(endswith(Office_Name,‘Realty’) and Street_City eq ‘Ventura’) or Salespersons add 5 gt 10
  • &: Multiple query options can be included at once, each separated by an “&”
    Example:
    • Example: Members?$expand=MemberDesignations($select=Designations)&$top=50&$select=MemberKeyNumeric

  • odata.nextLink: In some cases, the number of records matching the query parameters is greater than the number of results the server is capable of returning. If so, the results will include an “odata.nextLink” property that contains the exact URL and query needed to obtain the next set of matching results.

  • Single Entity: To return one specific Entity, the format is EntitySet(key). For example, if pulling back member number 100 from the Members entity set, the root URL would be appended with /Members(100). Some Entity Sets have multiple primary keys, in such cases the request format would be EntitySet(keyfield1=intvalue,keyfield2="charvalue",...). Please refer to the metadata to find the primary key(s) for each Entity Set.
    • Example: https://api.rapmagic.com/cust/odata/Members(100)
    • Example: https://api.rapmagic.com/cust/odata/InternetInformation(RecordKey=4,RecordType="MI",Association="ASOC")

Update Transactions

Records are Updated via an HTTP PATCH request against a Single Entity.

Required Headers: The following headers MUST be included with their respective values:

  • Authorization:bearer token
  • Content-Type:application/json

  • Optional Headers: By Default a successful PATCH request will return a 204 response. If you wish for the record targeted to be returned with a 200 response instead, you may use the following:

  • Prefer:return=representation
  • Note that you may include OData query criteria,such as $select, to narrow the fields shown in the result set when using the optional Prefer header.

    The body of the request must be a JSON object with the following format (quotes included): {"FieldName":"NewValue"}



    HTTP Response Codes

    Identity Server

    Code Text Description

    200

    OK

    Success

    400

    Bad Request
    “error: unsupported_grant_type”

    The grant type entered during Authentication is not supported.

    400

    Bad Request
    “error: invalid_grant”

    The username or password included were invalid

    400

    Bad Request
    “error: invalid_client”

    The client or client secret included were invalid.

    500

    Internal Server Error

    Most likely occurs due to an issue on the server side.

    Magic API

    Code Text Description

    200

    OK

    Success

    400

    Bad Request
    “The request is badly formed.”

    Likely the query needs to be URL encoded.

    400

    Bad Request
    “The query parameter 'x' is not supported.”

    The given query parameter is not valid.

    400

    Bad Request
    "Could not find a property named 'x' on type 'entityset'."

    The given property doesn’t exist in the entity set being queried.

    401

    Unauthorized
    “Authorization has been denied for this request.”

    The bearer token passed is expired or invalid.

    404

    Not Found

    An invalid resource was targeted

    500

    Internal Server Error

    Most likely occurs due to an issue on the server side.


    AMS StandardName Mapping: Version 7 File Layout

    MEMBER Mapping

    V7 Field Name API Entity Set API StandardName Mapping Notes

    Last Name

    Members

    MemberLastName

    First Name

    Members

    MemberFirstName

    Middle Initial

    Members

    MemberMiddleInitial

    Generation

    Members

    MemberNameSuffix

    Nickname

    Members

    MemberNickname

    Title

    Members

    JobTitle

    Salutation

    Members

    MemberNamePrefix

    Gender

    Not Currently Mapped

    Street Address

    Members

    MemberAddress1

    Care of

    Members

    MemberMailCareOf

    City

    Members

    MemberCity

    Home Zip Code

    Members

    MemberPostalCode

    Home Zip + 4

    Members

    MemberPostalCodePlus4

    OFC_Mail Address

    Offices

    OfficeMailAddress

    Check $metadata for Members to Offices navigation property details

    OFC_Mail Care of

    Offices

    OfficeMailCareOf

    Check $metadata for Members to Offices navigation property details

    OFC_Mail City

    Offices

    OfficeMailCity

    Check $metadata for Members to Offices navigation property details

    OFC_Mail State

    Offices

    OfficeMailStateOrProvince

    Check $metadata for Members to Offices navigation property details

    OFC_Mail Zip Code

    Offices

    OfficeMailPostalCode

    Check $metadata for Members to Offices navigation property details

    OFC_Mail Zip + 4

    Offices

    OfficeMailPostalCodePlus4

    Check $metadata for Members to Offices navigation property details

    Preferred Mail

    Members

    MemberPreferredMail

    Preferred Publication

    Members

    MemberPreferredPublication

    Home Phone Area

    Members

    MemberHomePhoneArea

    Home Phone Number

    Members

    MemberHomePhone

    Personal Fax Area

    Members

    MemberFaxAreaCode

    Personal Fax

    Members

    MemberFaxPhone

    Preferred Fax

    Not mapped

    CLNT_Off Pref Type

    Not mapped

    CLNT_Office Preference ID

    Not mapped

    CLNT_Office Preference ID

    Not mapped

    XMIT_Bill office Type Trans

    Not mapped

    ASSOC_Member Type

    MemberAssociation

    MemberAssociationMemberType

    Check $metadata for Members to MemberAssociation navigation property details

    ASSOC_Member Join Date

    MemberAssociation

    MemberAssociationJoinDate

    Check $metadata for Members to MemberAssociation navigation property details

    ASSOC_Orientation Date

    Not mapped

    ASSOC_Status

    MemberAssociation

    MemberAssociationStatus

    Check $metadata for Members to MemberAssociation navigation property details

    ASSOC_Status Date

    MemberAssociation

    MemberAssociationStatusDate

    Check $metadata for Members to MemberAssociation navigation property details

    Social Security Number

    Members

    MemberSocialSecurityNumber

    Social Security #

    Members

    MemberSocialSecurityNumber

    License #

    Members

    MemberStateLicense

    Birth Date

    Members

    MemberBirthDate

    Transfer Date

    Members

    MemberTransferDate

    Stop Mail

    Members

    MemberMailOptOutYN

    Allow Unsolicited Mail

    Members

    MemberUnsolicitedMailYN

    SUPL_Roster Indicator

    SUPLMLSMemberPRC

    RosterInd

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    ASOC_Online Status

    MemberAssociation

    OnlineStatus

    Check $metadata for Members to MemberAssociation navigation property details

    ASOC_Online Status Date

    MemberAssociation

    OnlineStatusDate

    Check $metadata for Members to MemberAssociation navigation property details

    SUPL_Access Ind

    SUPLMLSMemberPRC

    AccessInd

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Access Date

    SUPLMLSMemberPRC

    AccessDate

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    ASOC_Association ID

    MemberAssociation

    AssociationID

    Check $metadata for Members to MemberAssociation navigation property details

    INT_Web Page Address

    InternetInformation

    WebPageAddress

    Check $metadata for Members to InternetInformation navigation property details

    INT_E-mail Address

    InternetInformation

    EMailAddress

    Check $metadata for Members to InternetInformation navigation property details

    AM_MLS ID Translation

    Associations

    MLSTranslation

    PIN

    Members

    MemberPIN

    MLS ID

    Members

    MemberMlsId

    Ofc Phone Extention

    Members

    MemberPhoneExtension

    MLS ID

    Members

    MemberMlsId

    SUPL_Public ID

    SUPLMLSMemberPRC

    PublicID

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Private ID

    SUPLMLSMemberPRC

    PrivateID

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Primary User Class

    SUPLMLSMemberPRC

    PrimaryUserClass

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    IMS Logon ID

    Members

    InternetMemberServicesId

    Password

    Members

    MemberPassword

    Allow Unsolicited Fax

    Members

    MemberUnsolicitedFaxYN

    ASOC_Member Bill Type

    MemberAssociation

    MemberAssociationBillType

    Allow Unsolicitied Email

    Members

    MemberUnsolicitiedEmailYN

    Contact Primary Type

    Members

    PhoneType1

    Check $metadata for Mapping PhoneType between Member and PhoneNumbers

    Contact Primary Area

    PhoneNumbers

    PhoneAreaCode

    Contact Primary Number

    PhoneNumbers

    PhoneNumber

    ASOC_Designated Realtor

    MemberAssociation

    Full Name

    Members

    MemberFullName

    NRDS ID

    Members

    MemberNationalAssociationId

    Member Number

    Members

    MemberKeyNumeric

    SUPL_Secondary User Class

    SUPLMLSMemberPRC

    SecondaryUserClass

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Tax Access

    SUPLMLSMemberPRC

    TaxAccess

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Terminal Type

    SUPLMLSMemberPRC

    TerminalType

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Title Ind

    SUPLMLSMemberPRC

    TitleInd

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Upboard

    SUPLMLSMemberPRC

    Upboard

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Usboard

    SUPLMLSMemberPRC

    Usboard

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Multi Login

    SUPLMLSMemberPRC

    MultiLogin

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Menu

    SUPLMLSMemberPRC

    Menu

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Aff Type

    SUPLMLSMemberPRC

    AffType

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Yellow Pages

    SUPLMLSMemberPRC

    YellowPages

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_Tax County Access

    SUPLMLSMemberPRC

    TaxCountyAccess

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    SUPL_User Options

    SUPLMLSMemberPRC

    UserOptions

    Check $metadata for Members to SUPLMLSMemberPRC navigation property details

    Languages

    Not Mapped

    Preferred Media

    Members

    MemberPreferredMedia

    Preferred Billing

    Members

    MemberBillingPreference

    Phone On Roster

    Members

    MemberPhoneOnRosterYN

    Address On Roster

    Members

    AddressOnRosterYN

    On Roster

    Not Mapped

    Auth to Charge

    Members

    ChargeAuthorization

    Voting Precinct

    Members

    MemberVotingPrecinct

    License Type

    Members

    MemberStateLicenseType

    License Exp Date

    Members

    MemberStateLicenseExpirationDate

    Alternate Id

    Members

    MemberAlternateId

    NRDS Insert Date

    Members

    MemberNationalAssociationEntryDate

    Billing Cycle

    Members

    MemberBillingCycle

    BOR_Access Type

    Not Mapped